Developers — PASSID

Quickstart

From zero to verified in 3 steps.

Drop a PASSID verification field into your existing application form. It returns signed credential claims and verification metadata instead of self-reported data or redirects. The customer opens their PASSID app, taps Share, and reads out a one-time code. Claims land in your onVerified callback after verification.

1. Install the SDK and add one field to your form

Install @passidio/react and drop <PassidCodeVerification /> directly into your application form. It renders as a compact inline widget. Keep production API keys server-side and use the field to collect the applicant's one-time PASSID token.

✓ Embeds in any form — loan application, rental, onboarding, KYC

✓ No redirect, no new tab — customer stays inside your product

✓ Inline verification state after token validation

✓ Sandbox tokens included for deterministic integration testing

loan-application.jsx YOUR APP

// terminal
npm install @passidio/react @passidio/node

// app/api/passid-proxy/[...path]/route.ts — keeps your secret key server-side
import { createBridgeProxyHandler } from "@passidio/node/bridge-proxy";
const handler = createBridgeProxyHandler({ apiKey: process.env.PASSID_API_KEY! });
export const GET = handler;
export const POST = handler;

// drop into any existing form — no secret key in the browser
import { PassidCodeVerification } from "@passidio/react";

function LoanApplicationForm() {
  return (
    <form>
      {/* your existing fields */}
      <input name="full_name" />
      <input name="email" />

      {/* PASSID replaces self-reported income/identity */}
      <PassidCodeVerification
        proxyUrl="/api/passid-proxy"
        environment="live"
        onVerified={(result) => {
          setVerified(result.verified_claims);
        }}
      />

      <button type="submit">Submit</button>
    </form>
  );
}

2. Customer taps Share in their PASSID app and reads out a code

The customer opens their PASSID app and taps Share. The app generates a one-time share code (e.g. KE8V-3TXY-Z72L). They read it out or paste it into the field on your page. No QR scan required, no app redirect — it works over the phone, in person, or fully remote.

✓ One-time code bound to the applicant's selected credential claims

✓ Works in person, over phone, or fully online — no camera needed

✓ Customer controls what they share — consent is in-app

✓ Token status updates through the verification flow

Your form stays in place throughout

The customer can stay inside your application. They enter a one-time code, and verified financial claims arrive in your callback after the token is checked.

PASSID Mobile App — consent screen USER DEVICE

First National Bank
is requesting verification

Permissions:
✓ Income Verified
✓ Identity Verified
✓ Sanctions Screening

One-time use · Expires in 9:47

[ Decline ] [Share & Verify]

// User taps [Share & Verify]
// Claims fulfilled -> request resolved

3. Claims arrive in your callback

After the customer submits the code and the token is verified, onVerified(result) fires with the verified claims object under result.verified_claims. A verification.completed webhook can also hit your backend server.

✓ Verified credential claims — income, identity, sanctions, payment & savings behavior

✓ Claims are generated from credentialed sources, not self-reported form fields

✓ Also delivered via webhook — verification.completed fires on your server

✓ Report outcomes later with POST /v1/outcome to close the verification loop

onVerified(result) - fired after token verification YOUR APP

// result.verified_claims - verified credential object
{
  "identity_verified": true,
  "income_verified": true,
  "income_band": "$3,000–4,000/mo",
  "sanctions_screening_clear": true,
  "payment_behavior_verified": true,
  "savings_behavior_verified": true,
  "identity_and_fraud_checks_passed": true,
  "data_window_days": 180,
  "freshness_hours": 2,
  "linked_accounts": 3
}

// Your institution makes the decision - PASSID provides the claims
const c = result.verified_claims;
if (c.identity_verified && c.income_verified) routeApplicant();

For Developers

Two integration paths. One sandbox.

Whether you're verifying a token a customer already holds, or launching a Connect flow so the customer grants access themselves — both start in sandbox, both use the same key.

Path A — Verify

Verify a PASSID token with one API call.

Customer presents a scoped PassID token. Your backend verifies it with a single POST — returns signed credential claims, freshness, revocation state, and audit metadata.

Create sandbox key

Institution key used server-side. Demo tokens return synthetic sandbox claims for testing.

POST /api/v1/bridge/verify

Submit the scoped token with X-Institution-Key in the request header.

Apply institution policy

PASSID verifies the credential; your team owns the final decision.

📚 Verify docs 🧪 Create sandbox key

Path B — Connect

PassID Connect: customer grants access directly.

No PassID token required upfront. Customer clicks "Connect with PassID," approves, and you receive a connection_id. Most integrations complete in under a day.

POST /v1/connect/sessions

Send package-approved scopes, purpose, and return_url. Get back a hosted_url.

Redirect customer to hosted_url

PassID handles sign-in, identity verification, and consent UI entirely.

GET /v1/connect/sessions/:id

Verify the callback, store the connection_id, then fetch approved data endpoints.

📚 Connect docs 📄 Integration guide

PythonNode.jsRubyJavaGoREST APIWebhooks

verify.http
POST /api/v1/bridge/verify
X-Institution-Key: <institution_key>

{ "token": "psid_sandbox_demo_001" }

200 OK  sandbox
{
"credential_valid": true, "environment": "sandbox",
"token_status": "active", "signature_valid": true,
"claims": {
"identity_verified": true, "income_verified": true,
"income_band": "3000_4000_monthly",
"savings_consistency": "stable", "sanctions_clear": true
},
"freshness": { "data_window_days": 180, "valid_until": "2026-06-30T14:12:00Z" },
"revocation": { "revoked": false },
"audit": { "audit_id": "vrf_sandbox_82a4c9", "raw_transactions_included": false },
"decisioning": { "provided_by_passid": false }
}

passid-connect.http
// Step 1 — Create hosted session (server-side)
POST /v1/connect/sessions
Authorization: Bearer live_institution_key
{ "scopes": ["identity.read", "income.read"],
  "return_url": "https://yourapp.com/callback",
  "purpose": "Verify identity to open account" }
→ { "hosted_url": "https://app.passid.io/connect/authorize?..." }

// Step 2 — Redirect customer; PassID handles consent
// Customer approves → PassID redirects to return_url:
?session_id=pcs_live_...&connection_id=conn_live_...&status=approved

// Step 3 — Verify callback, then fetch authorized data
GET /v1/connect/sessions/:session_id
GET /v1/connect/connections/:id/identity
→ { identity, income, accounts, balances… }

Backend SDK

@passidio/node - server-side integration.

Protect API routes, verify tokens, and assemble verified claim packages from your backend. Works with Express, Next.js App Router, Next.js Pages Router, or any Node.js server.

Install

npm install @passidio/node

✓ passidMiddleware — Express drop-in route guard

✓ withPassid — Next.js App Router wrapper

✓ withPassidPages — Next.js Pages Router wrapper

✓ PASSIDClient — verify tokens, assemble claim packages, report outcomes

✓ verifyWebhookSignature — HMAC-SHA256 webhook verification

✓ Policy enforcement built in — requireClaims, freshness gates, identity & sanctions checks

server.ts — Express

import { passidMiddleware } from "@passidio/node";

app.post("/api/apply",
  passidMiddleware({
    apiKey: process.env.PASSID_API_KEY,
    policy: {
      requireClaims: ["income_verified", "sanctions_screening_clear"],
      maxCredentialAgeHours: 72,
    },
  }),
  (req, res) => {
    // req.passid is fully typed VerificationClaims
    // institution applies its own policy to the verified claims
    res.json({ verified: req.passid.identity_verified, income_band: req.passid.income_band });
  }
);

app/api/apply/route.ts — Next.js App Router

import { withPassid } from "@passidio/node";

export const POST = withPassid(
  {
    apiKey: process.env.PASSID_API_KEY,
    policy: {
      requireClaims: ["income_verified", "sanctions_screening_clear"],
      maxCredentialAgeHours: 72,
    },
  },
  async (req, claims) => {
    // claims is fully typed VerificationClaims
    // institution applies its own policy to the verified claims
    return Response.json({ verified: claims.identity_verified, income_band: claims.income_band });
  }
);

PASSIDClient - verify

import { PASSIDClient } from "@passidio/node";

const passid = new PASSIDClient({ apiKey: process.env.PASSID_API_KEY });

// Verify a token - returns the full signed claim set
const claims = await passid.verify(token);

// claims.identity_verified, claims.income_verified, ... -> signed claims
// claims.freshness_hours -> recency of the source signals
// Your institution applies its own policy
if (claims.identity_verified && claims.income_verified) {
routeApplicant(claims);
}

API Reference

Endpoints

All endpoints require X-Institution-Key: <your-api-key> unless marked public. Base URL: https://api.passid.io

SDK / QR Verification Flow

POST

/v1/sessions

Create a verification session

Called automatically by <PASSIDVerify /> on mount. Returns requestId, code (e.g. AB3X-7YQM), deepLink (passid://verify-request?r=…&i=…), and expiresAt. Body: { institutionName?, permissions?, ttlSeconds? } — TTL defaults to 600 s, max 3600 s.

GET

/v1/sessions/:requestId

Poll for completion

SDK polls this every 2.5 s after creating a request. Returns status: "pending" | "completed" | "declined" | "expired". When completed, response includes the full claims object and verifiedAt. Requires institution API key.

GET

/v1/sessions/:id/public

NO AUTH

Public request info (mobile app)

Called by the PASSID mobile app after scanning a QR — no institution API key needed. Returns institution name, requested permissions, and seconds until expiry. Returns 410 if already expired, fulfilled, or declined.

GET

/v1/sessions/by-code/:code/public

NO AUTH

Resolve 8-char fallback code

Resolves the human-readable code (e.g. AB3X-7YQM or AB3X7YQM) to the same response as the public request endpoint. Used by the in-app manual code entry screen.

Direct Token Verification

POST

/api/v1/bridge/verify

Verify a PASSID token

Accepts a PASSID share token directly. Returns signed claim summaries, signature status, freshness, revocation state, and audit metadata. The verifier response does not include raw financial statements or transaction feeds. Pass Idempotency-Key header so retries do not double-verify. Response includes X-PASSID-API-Version: 1.

Outcome Reporting

POST

/v1/outcome

Report verification outcome context

Report what happened after a PASSID-verified application — weeks or months later. Body: { token, outcome, productType?, amountUsd?, observationDays?, notes? }. Valid outcomes: repaid · no_default · delinquent · defaulted · fraud_confirmed · account_closed · other. The verification context at time of outcome reporting is captured automatically. One outcome per token per institution. Fires outcome.reported webhook.

GET

/v1/outcome/cohort

Your cohort calibration data

Returns outcome rates broken down by verification coverage level for all outcomes your institution has reported. Shown on your institution performance dashboard. Requires institution JWT.

Auth

POST

/api/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 entire token family.

GET

/api/v1

API version discovery

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

Webhooks

Event-driven verification.

verification.completed

Fires after a token is successfully verified. Includes signed claim summaries, signature status, freshness, revocation state, and audit identifiers. 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.

outcome.reported

Fires when an institution submits a verification outcome context via POST /v1/outcome. Payload includes the token, outcome type, product type, amount, and the verification context at time of outcome reporting. Use for audit trails and coverage improvement.

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": "signed_claim",
    "verified_claims": { "identity_verified": true, "income_verified": true, "sanctions_screening_clear": true, "payment_behavior_verified": true }
  }
}

Sandbox

Test without production data.

Use your sandbox API key with the same endpoints. The sandbox returns deterministic results — identical API shape to production, isolated from live data.

Get Connect sandbox credentials

Instant, self-serve, no approval needed. Creates a client_id / client_secret pair scoped to sandbox only — safe test data, zero production access.

Sandbox tokens for deterministic verifier testing

Use these exact strings with POST /api/v1/bridge/verify · { "token": "PASSID-SANDBOX-..." }

HIGH COVERAGE · KE->GB · Credential verified

PASSID-SANDBOX-TIER1AAA

Amara Osei · income OK · identity OK · sanctions clear · fraud checks passed · verified

PARTIAL COVERAGE · NG->US · Credential verified

PASSID-SANDBOX-TIER2BBB

Tobenna Eze · income OK · identity OK · sanctions clear · fraud checks passed · verified

TIER C · GH->EU · Partial claims

PASSID-SANDBOX-TIER3CCC

Efua Mensah · income OK · identity review · fraud medium · review

Permission Values — pass in permissions[] array

verified_credential_summaryFull standard claim set — all verified claims in one request

income_verifiedBoolean + income band (e.g. $3,000–$4,000/mo)

identity_verifiedIdentity verification boolean

sanctions_clearSanctions screening — OFAC · EU · UN watchlist clear

payment_reliabilityPayment behavior verified — derived from payment history

savings_consistencySavings behavior verified — derived from savings pattern

fraud_risklow / medium / high / not_assessed — currently returns not_assessed for every credential (no fraud-detection provider integrated yet)

Synthetic profiles

3 pre-seeded sandbox tokens (above) covering high coverage, partial coverage, and manual review states. Call POST /api/v1/bridge/verify with the exact token string to test the same response shape used by production verification.

Webhook simulator

Trigger verification.completed, verification.failed, and outcome.reported test events from your institution dashboard → API & Webhooks panel.

Open Sandbox Dashboard › Try PassID Connect

Common questions

What approved institutions ask before integration.

"Can we verify without receiving raw financial data?"

Yes. Use Credentials and Verify for scoped claims and verification metadata only. Choose Financial Data Access separately when your workflow requires customer-approved underlying data.

"Who makes the decision?"

The institution does. PASSID verifies credential claims. Your policy, risk, compliance, and operations teams own the final decision - not PASSID.

"Can we audit the verification?"

Verifier responses include token status, issuer signature state, freshness window, revocation state, and a unique audit ID. Institutions keep their own log of verification events.

"Can we start in sandbox before going live?"

Yes. Institutions test the full verify flow using sandbox credentials and synthetic demo tokens before any live rollout. Production access follows a live-access review.

"How long does PassID Connect integration take?"

Two backend API calls — one to create the connection request, one to fetch data after approval. PassID hosts the entire consent UI. Most institutions complete the integration in under a day; the sandbox is available immediately.

"What data does a connection_id unlock?"

Exactly what the customer approved — identity, income, accounts, balances, transactions, liabilities, or verification status, depending on which scopes you requested. The customer can revoke any connection from their PassID wallet at any time.