My consents · LSync — fiduciary API
Signed requests
Each call carries your API key, a timestamp, a nonce and an Ed25519 signature (made with the private key whose public key you registered) over: METHOD\nPATH_AND_QUERY\nTIMESTAMP\nNONCE\nSHA256_HEX_OF_BODY — the method in capitals, the path with its query exactly as sent, and the SHA-256 (hex) of the raw body (an empty body: the SHA-256 of "").
METHOD
PATH_AND_QUERY
TIMESTAMP
NONCE
SHA256_HEX_OF_BODYx-cm-key: cm_live_…
x-cm-timestamp: 1763112000000
x-cm-nonce: 9c1f7e0d2b6a4c3e
x-cm-signature: <base64 Ed25519 signature>Endpoints
Request body
{
"type": "object",
"properties": {
"principal": {
"type": "object",
"properties": {
"email": {
"type": "string",
"maxLength": 254
},
"mobile": {
"type": "string",
"maxLength": 20
}
},
"additionalProperties": false
},
"purposes": {
"type": "array",
"items": {
"type": "object",
"properties": {
"code": {
"type": "string",
"pattern": "^[a-z][a-z0-9-]{1,30}$"
},
"title": {
"type": "string",
"minLength": 2,
"maxLength": 120
},
"description": {
"type": "string",
"minLength": 5,
"maxLength": 1000
},
"dataItems": {
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 60
},
"minItems": 1,
"maxItems": 30
},
"retentionDays": {
"anyOf": [
{
"type": "integer",
"minimum": 1,
"maximum": 36500
},
{
"type": "null"
}
],
"default": null
}
},
"required": [
"code",
"title",
"description",
"dataItems"
],
"additionalProperties": false
},
"minItems": 1,
"maxItems": 20
},
"sources": {
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 40
},
"maxItems": 20,
"default": []
},
"noticeUrl": {
"type": "string",
"format": "uri",
"maxLength": 500
},
"noticeHash": {
"type": "string",
"pattern": "^[a-f0-9]{64}$"
},
"validityDays": {
"type": "integer",
"minimum": 1,
"maximum": 3650
}
},
"required": [
"principal",
"purposes",
"noticeUrl",
"noticeHash",
"validityDays"
],
"additionalProperties": false
}Response 201
{
"$ref": "#/components/schemas/RequestCreated"
}Response 200
{
"$ref": "#/components/schemas/Request"
}Response 200
{
"type": "object",
"properties": {
"artefacts": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Artefact"
}
}
},
"required": [
"artefacts"
]
}Response 200
{
"$ref": "#/components/schemas/Artefact"
}Response 200
{
"type": "object",
"properties": {
"shares": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ShareMeta"
}
}
},
"required": [
"shares"
]
}Request body
{
"type": "object",
"properties": {
"artefactId": {
"type": "string",
"minLength": 1,
"maxLength": 40
},
"purposeCode": {
"type": "string",
"minLength": 2,
"maxLength": 31
},
"envelope": {
"type": "object",
"properties": {
"v": {
"const": 1
},
"epk": {
"type": "string",
"maxLength": 200
},
"iv": {
"type": "string",
"maxLength": 40
},
"tag": {
"type": "string",
"maxLength": 40
},
"ct": {
"type": "string",
"maxLength": 3000000
}
},
"required": [
"v",
"epk",
"iv",
"tag",
"ct"
],
"additionalProperties": false
}
},
"required": [
"artefactId",
"purposeCode",
"envelope"
],
"additionalProperties": false
}Response 201
{
"type": "object",
"properties": {
"id": {
"type": "string"
},
"expiresAt": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"expiresAt"
]
}Response 200
{
"$ref": "#/components/schemas/ShareTaken"
}Request body
{
"type": "object",
"properties": {
"jws": {
"type": "string",
"minLength": 10,
"maxLength": 20000
}
},
"required": [
"jws"
],
"additionalProperties": false
}Response 200
{
"$ref": "#/components/schemas/VerifyResult"
}Response 200
{
"type": "object",
"properties": {
"fiduciaries": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PartnerFiduciary"
}
}
},
"required": [
"fiduciaries"
]
}Request body
{
"type": "object",
"properties": {
"legalName": {
"type": "string",
"minLength": 2,
"maxLength": 200
},
"name": {
"anyOf": [
{
"type": "string",
"minLength": 2,
"maxLength": 120
},
{
"type": "null"
}
],
"default": null
},
"contactEmail": {
"type": "string",
"format": "email",
"maxLength": 254
},
"partnerRef": {
"type": "string",
"pattern": "^[A-Za-z0-9._:-]{1,80}$"
},
"encryptionPublicKey": {
"anyOf": [
{
"type": "string",
"minLength": 40,
"maxLength": 2000
},
{
"type": "null"
}
],
"default": null
}
},
"required": [
"legalName",
"contactEmail",
"partnerRef"
],
"additionalProperties": false
}Response 201
{
"$ref": "#/components/schemas/PartnerFiduciary"
}Consent artefact
A compact JWS: header {alg: EdDSA, kid, typ: consent-artefact+jws}; payload {v, jti (artefact id), iss, fid (your id), req (request id), sub (the person's keyed reference), purposes, sources, notice {url, hash}, iat, nbf, exp}, serialised as canonical JSON (keys sorted). Verify with /.well-known/jwks.json.
Webhooks
POST to your webhook URL; body: a compact JWS (typ cm-notice+jws) whose payload is {id, event, at, data}; headers content-type application/jose, x-cm-event, x-cm-delivery. Verify it with /.well-known/jwks.json and answer 2xx. Not answered: tried again after 1, 5, 30, 120, 360, 1440 minutes, then given up.
{
"type": "object",
"description": "The payload of a webhook's JWS (typ cm-notice+jws)",
"properties": {
"id": {
"type": "string"
},
"event": {
"type": "string",
"enum": [
"consent.granted",
"consent.withdrawn",
"consent.expired",
"request.rejected",
"request.expired",
"share.waiting",
"mandate.active",
"mandate.revoked"
]
},
"at": {
"type": "string",
"format": "date-time"
},
"fiduciaryId": {
"type": "string",
"description": "The fiduciary the notice is about (a partner receives notices for every business it acts for)"
},
"data": {
"type": "object"
}
},
"required": [
"id",
"event",
"at",
"fiduciaryId",
"data"
]
}Data-blind shares
Data-blind shares: the SOURCE encrypts for the recipient's X25519 public key — an ephemeral X25519 key (epk: SPKI DER, base64), the shared secret through HKDF-SHA256 (salt: epk DER; info: "cm-share-v1|" + aad) to an AES-256-GCM key; iv 12 bytes, tag 16 bytes, ct base64; aad = artefactId|senderId|recipientId|purposeCode. At most 2 MB; waits 7 days; the platform cannot decrypt it and drops it once taken.
{
"type": "object",
"properties": {
"v": {
"const": 1
},
"epk": {
"type": "string",
"maxLength": 200
},
"iv": {
"type": "string",
"maxLength": 40
},
"tag": {
"type": "string",
"maxLength": 40
},
"ct": {
"type": "string",
"maxLength": 3000000
}
},
"required": [
"v",
"epk",
"iv",
"tag",
"ct"
],
"additionalProperties": false
}Technology partners
Technology partners (a platform that runs consent for many businesses) sign with their own key and a partner API key (cm_partner_…). Register a business with POST /api/v1/partner/fiduciaries; the business's contact e-mail gets a link to allow or decline. Once allowed, call any fiduciary endpoint for it with the header x-cm-fiduciary: <its id>, signed as METHOD\nPATH_AND_QUERY\nTIMESTAMP\nNONCE\nSHA256_HEX_OF_BODY\nFIDUCIARY_ID (the last line empty on /api/v1/partner/*). Notices for the businesses you act for come to your webhook, each with fiduciaryId; mandate.active and mandate.revoked tell you when a business allows or withdraws you. A business can withdraw you at any time; your calls for it then get 403.
METHOD
PATH_AND_QUERY
TIMESTAMP
NONCE
SHA256_HEX_OF_BODY
FIDUCIARY_IDx-cm-key: cm_partner_…
x-cm-fiduciary: <the business's fiduciary id>
x-cm-timestamp: 1763112000000
x-cm-nonce: 9c1f7e0d2b6a4c3e
x-cm-signature: <base64 Ed25519 signature>Verify a person's record
node verify-record.mjs my-consent-record.json jwks.jsonverify-record.mjs