Your first call

Sandbox prerequisites, app setup in Console, and hosted OIDC or REST identification.

Your first integration calls should use sandbox (https://s.pasby.africa). Production requires an active billing plan for your organisation.

Prerequisites

Complete How to get API keys first. You should have:

A Console account with at least one organisation
Generated API configuration for that organisation (bk-test_…)
A sandbox app with client secret (and communication keys if you will decrypt claims on the server)

Prepare your app in Console

Before starting flows, confirm in app settings:

Item	Why
Client ID	Identifies your app in authorize and flow models
Client secret	Required for v2 (`x-access-secret`)
Communication keys	Required on backend stacks to decrypt claims after identification

You may need a linked pasby eID on your Console profile to generate secrets or keys. Open your profile from the organisation dashboard if any action is blocked.

Choose how to integrate

Approach	Best for
REST API v2	Mobile, server-driven signing, wildcard QR, documents
Hosted OIDC	Web apps that redirect users to pasby identification with PKCE

SDKs wrap both styles — see Client libraries.

Option A — REST identification (wildcard)

Matches the Quickstart: no NIN upfront, returns seeds for QR.

curl -sS -X POST "https://s.pasby.africa/api/v2/identification/wildcard" \
  -H "x-api-key: bk-test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "signup",
    "claims": ["naming.family", "naming.given", "contact.email"],
    "seeds": 4,
    "payload": "Create your account with pasby"
  }'

Poll with flow ping, then decrypt claims. Full SDK map: TypeScript SDK.

Option B — Hosted authentication (OIDC)

pasby 2.0 added OAuth-style hosted identification at oauth.pasby.africa. Use an official SDK — they handle PKCE, redirects, and token exchange.

import { LoginButton } from "@finsel-dgi/pasby-next";

export function SignIn() {
  return <LoginButton action="login" fallbackPath="/dashboard" variant="dark" />;
}

Wire app/api/eid/[auth]/route.ts with handler() from @finsel-dgi/pasby-next/server. Full setup: Next.js OIDC.

import { loginWithSecret } from "@finsel-dgi/pasby-react/server";

const { redirect, pkceverifier } = await loginWithSecret({
  claims: ["naming.family", "naming.given", "contact.email"],
  action: "signup",
  payload: "Create your account with pasby",
  redirect_uri: "https://your-app.com/auth/callback",
});

Full sequence: OIDC quickstart · React OIDC · PKCE.

What's next?

Integration path — pick endpoints for your product
Identification guide — same-device, different-device, wildcard
SampleCode on GitHub — reference server implementation