{"openapi":"3.1.0","info":{"title":"My consents · LSync — fiduciary API","version":"1","description":"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 \"\").\n\nA 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.\n\nPOST 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.\n\nData-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.\n\nTechnology 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."},"servers":[{"url":"https://myconsent.lsync.io"}],"paths":{"/api/v1/requests":{"post":{"summary":"Ask a person for consent","security":[{"apiKey":[]}],"parameters":[{"name":"x-cm-key","in":"header","required":true,"schema":{"type":"string"},"description":"Your API key"},{"name":"x-cm-timestamp","in":"header","required":true,"schema":{"type":"string","pattern":"^\\d{13}$"},"description":"Milliseconds since 1970; within 5 minutes of the platform's clock"},{"name":"x-cm-nonce","in":"header","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{16,64}$"},"description":"Never used before (remembered 10 minutes)"},{"name":"x-cm-signature","in":"header","required":true,"schema":{"type":"string"},"description":"Ed25519 signature (base64) over the signature base"},{"name":"x-cm-fiduciary","in":"header","required":false,"schema":{"type":"string"},"description":"Partners only: the business you act for (its fiduciary id); the sixth line of the signature base"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"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}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestCreated"}}}},"4XX":{"description":"Refused","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/requests/{id}":{"get":{"summary":"A request and its artefact","security":[{"apiKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"x-cm-key","in":"header","required":true,"schema":{"type":"string"},"description":"Your API key"},{"name":"x-cm-timestamp","in":"header","required":true,"schema":{"type":"string","pattern":"^\\d{13}$"},"description":"Milliseconds since 1970; within 5 minutes of the platform's clock"},{"name":"x-cm-nonce","in":"header","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{16,64}$"},"description":"Never used before (remembered 10 minutes)"},{"name":"x-cm-signature","in":"header","required":true,"schema":{"type":"string"},"description":"Ed25519 signature (base64) over the signature base"},{"name":"x-cm-fiduciary","in":"header","required":false,"schema":{"type":"string"},"description":"Partners only: the business you act for (its fiduciary id); the sixth line of the signature base"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Request"}}}},"4XX":{"description":"Refused","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/artefacts":{"get":{"summary":"Your artefacts","security":[{"apiKey":[]}],"parameters":[{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["ACTIVE","WITHDRAWN","EXPIRED"]}},{"name":"x-cm-key","in":"header","required":true,"schema":{"type":"string"},"description":"Your API key"},{"name":"x-cm-timestamp","in":"header","required":true,"schema":{"type":"string","pattern":"^\\d{13}$"},"description":"Milliseconds since 1970; within 5 minutes of the platform's clock"},{"name":"x-cm-nonce","in":"header","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{16,64}$"},"description":"Never used before (remembered 10 minutes)"},{"name":"x-cm-signature","in":"header","required":true,"schema":{"type":"string"},"description":"Ed25519 signature (base64) over the signature base"},{"name":"x-cm-fiduciary","in":"header","required":false,"schema":{"type":"string"},"description":"Partners only: the business you act for (its fiduciary id); the sixth line of the signature base"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"artefacts":{"type":"array","items":{"$ref":"#/components/schemas/Artefact"}}},"required":["artefacts"]}}}},"4XX":{"description":"Refused","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/artefacts/{id}":{"get":{"summary":"One artefact (yours, or one naming you as a source)","security":[{"apiKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"x-cm-key","in":"header","required":true,"schema":{"type":"string"},"description":"Your API key"},{"name":"x-cm-timestamp","in":"header","required":true,"schema":{"type":"string","pattern":"^\\d{13}$"},"description":"Milliseconds since 1970; within 5 minutes of the platform's clock"},{"name":"x-cm-nonce","in":"header","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{16,64}$"},"description":"Never used before (remembered 10 minutes)"},{"name":"x-cm-signature","in":"header","required":true,"schema":{"type":"string"},"description":"Ed25519 signature (base64) over the signature base"},{"name":"x-cm-fiduciary","in":"header","required":false,"schema":{"type":"string"},"description":"Partners only: the business you act for (its fiduciary id); the sixth line of the signature base"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Artefact"}}}},"4XX":{"description":"Refused","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/shares":{"get":{"summary":"Shares waiting for you","security":[{"apiKey":[]}],"parameters":[{"name":"x-cm-key","in":"header","required":true,"schema":{"type":"string"},"description":"Your API key"},{"name":"x-cm-timestamp","in":"header","required":true,"schema":{"type":"string","pattern":"^\\d{13}$"},"description":"Milliseconds since 1970; within 5 minutes of the platform's clock"},{"name":"x-cm-nonce","in":"header","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{16,64}$"},"description":"Never used before (remembered 10 minutes)"},{"name":"x-cm-signature","in":"header","required":true,"schema":{"type":"string"},"description":"Ed25519 signature (base64) over the signature base"},{"name":"x-cm-fiduciary","in":"header","required":false,"schema":{"type":"string"},"description":"Partners only: the business you act for (its fiduciary id); the sixth line of the signature base"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"shares":{"type":"array","items":{"$ref":"#/components/schemas/ShareMeta"}}},"required":["shares"]}}}},"4XX":{"description":"Refused","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"summary":"Push encrypted data for an artefact's holder (you as its source)","security":[{"apiKey":[]}],"parameters":[{"name":"x-cm-key","in":"header","required":true,"schema":{"type":"string"},"description":"Your API key"},{"name":"x-cm-timestamp","in":"header","required":true,"schema":{"type":"string","pattern":"^\\d{13}$"},"description":"Milliseconds since 1970; within 5 minutes of the platform's clock"},{"name":"x-cm-nonce","in":"header","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{16,64}$"},"description":"Never used before (remembered 10 minutes)"},{"name":"x-cm-signature","in":"header","required":true,"schema":{"type":"string"},"description":"Ed25519 signature (base64) over the signature base"},{"name":"x-cm-fiduciary","in":"header","required":false,"schema":{"type":"string"},"description":"Partners only: the business you act for (its fiduciary id); the sixth line of the signature base"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"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}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"expiresAt":{"type":"string","format":"date-time"}},"required":["id","expiresAt"]}}}},"4XX":{"description":"Refused","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/shares/{id}/take":{"post":{"summary":"Take a share (once; the platform then drops the ciphertext)","security":[{"apiKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"x-cm-key","in":"header","required":true,"schema":{"type":"string"},"description":"Your API key"},{"name":"x-cm-timestamp","in":"header","required":true,"schema":{"type":"string","pattern":"^\\d{13}$"},"description":"Milliseconds since 1970; within 5 minutes of the platform's clock"},{"name":"x-cm-nonce","in":"header","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{16,64}$"},"description":"Never used before (remembered 10 minutes)"},{"name":"x-cm-signature","in":"header","required":true,"schema":{"type":"string"},"description":"Ed25519 signature (base64) over the signature base"},{"name":"x-cm-fiduciary","in":"header","required":false,"schema":{"type":"string"},"description":"Partners only: the business you act for (its fiduciary id); the sixth line of the signature base"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShareTaken"}}}},"4XX":{"description":"Refused","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/verify":{"post":{"summary":"Check an artefact (signature and status now) or a person's acknowledgement (signature)","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"jws":{"type":"string","minLength":10,"maxLength":20000}},"required":["jws"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerifyResult"}}}},"4XX":{"description":"Refused","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/partner/fiduciaries":{"get":{"summary":"Partners: the businesses you registered, with their permission's status","security":[{"apiKey":[]}],"parameters":[{"name":"x-cm-key","in":"header","required":true,"schema":{"type":"string"},"description":"Your API key"},{"name":"x-cm-timestamp","in":"header","required":true,"schema":{"type":"string","pattern":"^\\d{13}$"},"description":"Milliseconds since 1970; within 5 minutes of the platform's clock"},{"name":"x-cm-nonce","in":"header","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{16,64}$"},"description":"Never used before (remembered 10 minutes)"},{"name":"x-cm-signature","in":"header","required":true,"schema":{"type":"string"},"description":"Ed25519 signature (base64) over the signature base"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"fiduciaries":{"type":"array","items":{"$ref":"#/components/schemas/PartnerFiduciary"}}},"required":["fiduciaries"]}}}},"4XX":{"description":"Refused","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"summary":"Partners: register a business (it allows or declines by an e-mailed link)","security":[{"apiKey":[]}],"parameters":[{"name":"x-cm-key","in":"header","required":true,"schema":{"type":"string"},"description":"Your API key"},{"name":"x-cm-timestamp","in":"header","required":true,"schema":{"type":"string","pattern":"^\\d{13}$"},"description":"Milliseconds since 1970; within 5 minutes of the platform's clock"},{"name":"x-cm-nonce","in":"header","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{16,64}$"},"description":"Never used before (remembered 10 minutes)"},{"name":"x-cm-signature","in":"header","required":true,"schema":{"type":"string"},"description":"Ed25519 signature (base64) over the signature base"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"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}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerFiduciary"}}}},"4XX":{"description":"Refused","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/.well-known/jwks.json":{"get":{"summary":"The platform's signing keys (JWKS)","security":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"keys":{"type":"array","items":{"type":"object"}}}}}}}}}}},"webhooks":{"notice":{"post":{"summary":"A notice to your webhook URL","requestBody":{"content":{"application/jose":{"schema":{"type":"string","description":"Compact JWS; its payload is a Notice"}}}},"responses":{"200":{"description":"Received"}}}}},"components":{"schemas":{"Purpose":{"type":"object","properties":{"code":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"dataItems":{"type":"array","items":{"type":"string"}},"retentionDays":{"anyOf":[{"type":"integer"},{"type":"null"}]}},"required":["code","title","description","dataItems","retentionDays"]},"Artefact":{"type":"object","properties":{"id":{"type":"string"},"requestId":{"type":"string"},"fiduciaryId":{"type":"string"},"purposes":{"type":"array","items":{"$ref":"#/components/schemas/Purpose"}},"sources":{"type":"array","items":{"type":"string"}},"validFrom":{"type":"string","format":"date-time"},"validTo":{"type":"string","format":"date-time"},"status":{"type":"string","enum":["ACTIVE","WITHDRAWN","EXPIRED"]},"withdrawnAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"jws":{"type":"string","description":"Compact JWS (EdDSA), typ consent-artefact+jws"},"jwsHash":{"type":"string","description":"SHA-256 of the JWS (hex)"}},"required":["id","requestId","fiduciaryId","purposes","sources","validFrom","validTo","status","withdrawnAt","jws","jwsHash"]},"RequestCreated":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["PENDING"]},"url":{"type":"string","format":"uri","description":"The page the person approves on"},"expiresAt":{"type":"string","format":"date-time"}},"required":["id","status","url","expiresAt"]},"Request":{"type":"object","properties":{"id":{"type":"string"},"fiduciaryId":{"type":"string"},"purposes":{"type":"array","items":{"$ref":"#/components/schemas/Purpose"}},"sources":{"type":"array","items":{"type":"string"}},"noticeUrl":{"type":"string"},"noticeHash":{"type":"string"},"validityDays":{"type":"integer"},"status":{"type":"string","enum":["PENDING","APPROVED","REJECTED","EXPIRED"]},"expiresAt":{"type":"string","format":"date-time"},"decidedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time"},"artefact":{"anyOf":[{"$ref":"#/components/schemas/Artefact"},{"type":"null"}]}},"required":["id","status","purposes","expiresAt","artefact"]},"ShareMeta":{"type":"object","properties":{"id":{"type":"string"},"artefactId":{"type":"string"},"senderId":{"type":"string"},"purposeCode":{"type":"string"},"size":{"type":"integer"},"ctHash":{"type":"string"},"status":{"type":"string","enum":["PENDING","DELIVERED","EXPIRED"]},"expiresAt":{"type":"string","format":"date-time"},"createdAt":{"type":"string","format":"date-time"}},"required":["id","artefactId","senderId","purposeCode","size","ctHash","status","expiresAt","createdAt"]},"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},"ShareTaken":{"allOf":[{"$ref":"#/components/schemas/ShareMeta"},{"type":"object","properties":{"envelope":{"$ref":"#/components/schemas/Envelope"},"aad":{"type":"string","description":"artefactId|senderId|recipientId|purposeCode"}},"required":["envelope","aad"]}]},"VerifyResult":{"type":"object","properties":{"valid":{"type":"boolean"},"kind":{"type":"string","enum":["artefact","acknowledgement"]},"status":{"type":"string"},"inForce":{"type":"boolean"},"payload":{"type":"object"},"reason":{"type":"string"}},"required":["valid"]},"Error":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]},"Notice":{"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"]},"PartnerFiduciary":{"type":"object","properties":{"mandateId":{"type":"string"},"fiduciaryId":{"type":"string"},"partnerId":{"type":"string"},"partner":{"anyOf":[{"type":"string"},{"type":"null"}]},"partnerRef":{"type":"string"},"business":{"anyOf":[{"type":"string"},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"fiduciaryStatus":{"anyOf":[{"type":"string","enum":["PENDING","ACTIVE","SUSPENDED","REJECTED"]},{"type":"null"}]},"status":{"type":"string","enum":["PENDING","ACTIVE","DECLINED","REVOKED"],"description":"The business's permission: waiting, allowed, declined or withdrawn"},"confirmedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"revokedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time"}},"required":["mandateId","fiduciaryId","partnerRef","status","createdAt"]}},"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"x-cm-key","description":"A fiduciary's key (cm_live_…) or a partner's (cm_partner_…)"}}}}