Developer integration

Ask before you use data.

Integrating ConsentOS takes four calls: announce your service, request permission, enforce the grant before doing the work, and verify receipts when you need proof. The @consentos/sdk package wraps them with no dependencies.

1. 1. Create a client — on your server

   Your API key identifies your service and never leaves your backend. In this build Pixly is seeded as a verified service; a full deployment would issue keys from a developer console.

   import { ConsentOS } from "@consentos/sdk"
   
   export const consent = new ConsentOS({
     serviceId: "pixly",
     apiUrl: "https://consentos.vercel.app",
     apiKey: process.env.CONSENTOS_API_KEY, // server-side only
   })

2. 2. Request permission

   Say exactly what you want: the data, the purpose, how long you keep it, whether it leaves your company. The user's rules decide deterministically. You get a decision, a machine-readable reason and — for ALLOW and DENY — a signed receipt. An ALLOW receipt is your grant.

   const result = await consent.request({
     userId,
     dataType: "uploaded_images",
     purpose: "personalization",
     retentionDays: 30,
     thirdPartySharing: false,
   })
   
   switch (result.decision) {
     case "ALLOW":
       await saveGrant(userId, "personalization", result.receiptId)
       break
     case "DENY":
       showBlocked(result.reason) // e.g. RETENTION_EXCEEDS_LIMIT
       break
     case "REQUIRE_USER":
       // the user's rules want to be asked; they answer in ConsentOS
       const answer = await consent.waitForDecision(result.requestId)
       break
   }

   {
     "requestId": "0f6c1d0e-…",
     "decision": "DENY",
     "reasonCode": "PURPOSE_DENIED",
     "reason": "Foundation-model training is blocked by the user's privacy policy.",
     "details": { "rule": "policy.foundationModelTraining" },
     "evaluatedAt": "2026-09-26T14:32:08.114Z",
     "policyVersion": 3,
     "receiptId": "a1d4…",
     "receiptUrl": "https://consentos.vercel.app/receipts/a1d4…",
     "engineVersion": "1.0.0"
   }

3. 3. Enforce before you do the work

   This is the part that makes consent real. Your protected endpoint asks ConsentOS whether the grant exists, belongs to this user and service, covers this purpose and data, is not revoked, and still verifies. If not, refuse. Do not trust a decision your own frontend reports.

   export async function POST(req: Request) {
     const { grantId } = await req.json()
     const check = await consent.checkGrant({
       userId,
       purpose: "foundation_model_training",
       dataType: "uploaded_images",
       receiptId: grantId,
     })
   
     if (!check.authorized) {
       return Response.json(
         { error: check.code, message: check.message }, // CONSENT_VIOLATION | CONSENT_REVOKED
         { status: 403 },
       )
     }
   
     return startTraining()
   }

4. 4. Announce your service to the extension

   One line in the browser lets the ConsentOS extension recognise your site, show the user what you are allowed to do, and refresh the moment a decision lands. The extension checks your page's origin against your registered domain, so another site cannot claim to be you.

   import { announceService, notifyDecision } from "@consentos/sdk/browser"
   
   announceService({ serviceId: "pixly", name: "Pixly" })
   
   // after your backend receives a decision:
   notifyDecision({ requestId })

5. 5. Verify receipts

   Receipts are SHA-256 over canonical JSON (sorted keys, no whitespace), signed with Ed25519. Anyone can check them against the public keys; no ConsentOS account needed.

   const result = await consent.verifyReceipt(receiptId)
   // { valid: true, payloadIntact: true, signatureValid: true,
   //   requestHashValid: true, policyHashValid: true, revoked: false, … }