Référence JSON

Cette section documente champ par champ les artéfacts tels qu'ils circulent sur le réseau. Chaque exemple est la forme réelle que construit le code d'Agreely, et non une illustration. À lire en parallèle du protocole pour la cryptographie derrière chaque champ.

• La demande de consentement (cette page) : l'offre signée qu'une entreprise émet.
• Le reçu de consentement : le justificatif vérifiable que reçoit le citoyen.
• Documents DID : entreprise et citoyen.
• Vérifier un reçu : les quatre contrôles qu'effectue un auditeur.

#La demande de consentement (l'offre signée)

Lorsqu'une entreprise émet une demande de consentement, Agreely construit une offre sans nombres, signe ses octets JCS-canoniques avec la clé de l'entreprise, et enveloppe la signature comme une preuve Data Integrity companySig. Chaque valeur est une chaîne, de sorte que les octets canoniques qu'un vérificateur redérive ne peuvent jamais diverger.

{
  "requestId": "0x4b08245219c0e1a2b3c4d5e6f70819a2b3c4d5e6f70819a2b3c4d5e6f7081234",
  "issuer": "did:web:agreely.ca:c:acme",
  "subject": {
    "ref": "cust_8812",
    "status": "known"
  },
  "consent": {
    "action": "grant",
    "items": [
      {
        "itemId": "0x9a2b3c4d5e6f70819a2b3c4d5e6f70819a2b3c4d5e6f70819a2b3c4d5e6f7081",
        "category": "phone number",
        "purpose": "billing"
      }
    ]
  },
  "nonce": "0x7081234b3c4d5e6f70819a2b3c4d5e6f70819a2b3c4d5e6f70819a2b3c4d5e6f",
  "validUntil": "2031-01-01T00:00:00Z",
  "createdAt": "2026-06-26T15:00:00Z",
  "expiresAt": "2026-07-26T15:00:00Z",
  "companySig": {
    "type": "DataIntegrityProof",
    "cryptosuite": "eddsa-jcs-2022",
    "created": "2026-06-26T15:00:00Z",
    "verificationMethod": "did:web:agreely.ca:c:acme#kms-1",
    "proofPurpose": "assertionMethod",
    "proofValue": "z3Ge8wQ5...base58btc..."
  }
}

#Champ par champ

Champ	Type	Signification
requestId	0x + 64 hex	La poignée du protocole : 32 octets aléatoires frais, jamais dérivés. L'identifiant public partout, jamais un uuid interne.
issuer	chaîne	Le DID de l'entreprise, did:web:agreely.ca:c:{slug}.
subject.ref	chaîne	La propre référence client de l'entreprise. Jamais un DID de citoyen.
subject.status	chaîne	known ou unonboarded (selon que le destinataire possède déjà un DID de citoyen).
consent.action	chaîne	grant.
consent.items[].itemId	0x + 64 hex	Une poignée opaque aléatoire fraîche pour cet élément.
consent.items[].category	chaîne	La clé de catégorie normalisée (valeur canonique en minuscules), pas le libellé d'affichage.
consent.items[].purpose	chaîne	La clé de finalité normalisée.
nonce	0x + 64 hex	Nonce aléatoire à usage unique, lié au défi d'approbation afin que la réponse ne puisse être rejouée.
validUntil	RFC 3339	La durée de vie du consentement s'il est approuvé.
createdAt	RFC 3339	Quand l'offre a été créée.
expiresAt	RFC 3339	L'échéance de réponse (30 jours). Une demande en attente passé ce délai bascule à expired.
companySig	objet	La preuve Data Integrity eddsa-jcs-2022 sur l'offre.

#Au repos

L'objet qu'Agreely stocke (chiffré sous la DEK du locataire) est l'offre plus trois champs d'enveloppe, qui ne sont pas couverts par companySig :

{
  "...": "all offer fields above",
  "companySig": { "...": "the proof" },
  "status": "pending",
  "result": { "receipts": null, "settledAt": null }
}

status progresse vers approved, refused, expired ou revoked_before_action; result est rempli lorsque la demande est réglée.

#Les formes exposées au SDK

L'API /v1 renvoie des vues allégées d'une demande plutôt que l'objet signé brut. La réponse d'émission (IssuedRequest) et la vue liste/affichage (ConsentRequest) sont documentées dans la référence de l'API et la spécification interactive.