Developers — PASSID

Quickstart

The full protocol in 3 steps.

PASSID is a three-actor protocol: your institution requests a credential, the user consents in their wallet, and you verify the claims in one API call. Here's the full runnable flow.

① Institution sends a verification request

Your backend calls POST /api/v1/bridge/share/create with the claims you need. PASSID returns a one-time share token. The applicant presents it to your verifier.

✓ Specify exactly which claims you need — income, sanctions, DSCR band

✓ User is notified in real-time — no email, no form to fill

✓ Request expires in 10 minutes if unanswered

POST /api/v1/bridge/share/create YOUR BACKEND

const req = await passid.request({

  applicant_id: "user_7f3k9x",

  claims_required: [

    "income_verified",

    "sanctions_clear",

    "dscr_above_1_2",

    "identity_liveness"

  ],

  corridor: "NG-UK",

  webhook_url: "https://yourbank.com/passid",

  expires_in: 600 // 10 min

});

// Response

// { request_id: "req_4k9xP2", status: "pending",

//   wallet_notified: true, expires_at: "..." }

API Reference

Endpoints

POST

/api/v1/bridge/verify

Verify a PASSID credential

Accepts a PASSID token. Returns credential validity, signal claims, freshness, and proof status. Pass Idempotency-Key header to make retries safe. Response includes X-PASSID-API-Version: 1.

POST

/api/v1/bridge/share/create

Create a share token

Issues a one-time or multi-use share token the applicant presents to your verifier. Optionally restrict to a specific institution, set expiry, and choose revocability.

POST

/api/v1/institution/token/refresh

Refresh session token

Exchange a 30-day refresh token for a new access token + rotated refresh token. Enables long-lived sessions without re-authentication. Reuse of a consumed token triggers automatic revocation of the token family.

GET

/api/v1

API version discovery

Returns the current API version, release date, and a full map of all v1 endpoint paths. Use to confirm your integration is on the versioned surface.

Webhooks

Event-driven verification.

verification.completed

Fires immediately after a token is successfully verified. Includes all proven claims, proof type, and expiry. Safe to retry — use Idempotency-Key on the verify call to prevent duplicate webhooks.

verification.failed

Fires when a token is rejected — expired, revoked, or institution mismatch. Includes deny_reason string. Only fired when the request carries a valid institution API key.

webhook.test

Manual ping from your dashboard to confirm your endpoint is reachable. Use to validate signature verification before going live.

Delivery: HMAC-SHA256 signed via X-PASSID-Signature: sha256=<hex>. Automatic retries on non-2xx: immediate → 30 s → 5 min → 30 min → 2 h (5 attempts total). Pending deliveries survive server restarts.

Webhook payload — verification.completed · X-PASSID-Signature: sha256=…

          {

            "event": "verification.completed",

            "institution_id": "42",

            "timestamp": "2026-03-27T10:22:14Z",

            "data": {

              "token": "pid_K3px...",

              "verified_at": "2026-03-27T10:22:14Z",

              "proof_type": "groth16/bn254",

              "claims": { "tier": "B", "fsi_score": 801, "income_verified": true, "sanctions_clear": true }

            }

          }

Integrate in hours, not months.

The full protocol in 3 steps.

Endpoints

Event-driven verification.

Test without production data.