Skip to content

My consents · LSync — fiduciary API

openapi.jsonjwks.jsonApply

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

POST /api/v1/requests · signed
Ask a person for consent
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" }
GET /api/v1/requests/{id} · signed
A request and its artefact
Response 200{ "$ref": "#/components/schemas/Request" }
GET /api/v1/artefacts · signed
Your artefacts
Response 200{ "type": "object", "properties": { "artefacts": { "type": "array", "items": { "$ref": "#/components/schemas/Artefact" } } }, "required": [ "artefacts" ] }
GET /api/v1/artefacts/{id} · signed
One artefact (yours, or one naming you as a source)
Response 200{ "$ref": "#/components/schemas/Artefact" }
GET /api/v1/shares · signed
Shares waiting for you
Response 200{ "type": "object", "properties": { "shares": { "type": "array", "items": { "$ref": "#/components/schemas/ShareMeta" } } }, "required": [ "shares" ] }
POST /api/v1/shares · signed
Push encrypted data for an artefact's holder (you as its source)
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" ] }
POST /api/v1/shares/{id}/take · signed
Take a share (once; the platform then drops the ciphertext)
Response 200{ "$ref": "#/components/schemas/ShareTaken" }
POST /api/v1/verify · public
Check an artefact (signature and status now) or a person's acknowledgement (signature)
Request body{ "type": "object", "properties": { "jws": { "type": "string", "minLength": 10, "maxLength": 20000 } }, "required": [ "jws" ], "additionalProperties": false }
Response 200{ "$ref": "#/components/schemas/VerifyResult" }
GET /api/v1/partner/fiduciaries · partner
Partners: the businesses you registered, with their permission's status
Response 200{ "type": "object", "properties": { "fiduciaries": { "type": "array", "items": { "$ref": "#/components/schemas/PartnerFiduciary" } } }, "required": [ "fiduciaries" ] }
POST /api/v1/partner/fiduciaries · partner
Partners: register a business (it allows or declines by an e-mailed link)
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