Handling encrypted claims

After an identification flow completes, POST /api/v2/flow/ping returns consented claims encrypted with your app's public key. You decrypt them server-side with the matching private key from the pasby console.

Prerequisites

Communication keys downloaded for your app
Private key stored only on your server (never in the browser)
Flow request id from the create identification response

1. Poll until claims appear

curl -sS -X POST "https://s.pasby.africa/api/v2/flow/ping" \
  -H "x-api-key: bk-test_YOUR_KEY" \
  -H "x-access-secret: YOUR_APP_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "request": "req_YOUR_FLOW_ID" }'

When data.request.claims is populated and the flow is not cancelled, proceed to decryption.

2. Decrypt claim strings

Each leaf value in the claims object is an RSA-encrypted string. Decrypt per field with your app private key.

import JSEncrypt from "node-jsencrypt";

function decryptClaims(privateKeyPem, encrypted) {
  const crypt = new JSEncrypt();
  crypt.setKey(privateKeyPem);
  const out = {};

  for (const [group, fields] of Object.entries(encrypted)) {
    out[group] = {};
    for (const [key, value] of Object.entries(fields)) {
      if (typeof value === "string") {
        out[group][key] = crypt.decrypt(value);
      }
    }
  }
  return out;
}

Reference implementation: SampleCode/server/src/services/pasby.ts.

3. Map to your user model

Persist only fields your product needs. Claim keys are defined in the Claims reference.

OIDC resource returns claims in a different envelope (Bearer token + session challenge). Use this guide for REST identification + flow ping integrations.

Troubleshooting

Symptom	Check
`claims` always empty	User has not finished on device; keep polling
Decrypt returns `false`	Wrong private key; key pair mismatch with console
Partial claims	User denied some fields; request fewer claims