Identification

Same-device, different-device, and wildcard identification with full request and response examples.

Identification scopes simplify authentication, KYC, and registration. Supported actions: login, signup, and link.

Sandbox base URL: https://s.pasby.africa

Node.js integrations: @finsel-dgi/pasby — pasby.identification.sameDevice, differentDevice, wildcard. · Use API v2 with x-api-key and x-access-secret unless you are on legacy v1.

Identification model

Every create response includes a request object. Same-device flows also return a link to open on the client.

idstring
Unique flow identifier (e.g. req_…). Pass to flow ping.
consumerstring
Organisation (consumer) id that created the flow.
appstring
Application id.
namestring
Human-readable app name.
userstring
Target user NIN when set (different-device).
modestring
Always identification for these endpoints.
iatnumber
Created-at unix timestamp.
expnumber
Expiration unix timestamp.
acquireClaimsstring[]
Claim keys requested.
signaturestring
JWT stamp from pasby server — validates flow origin.
ipstring
IP where the flow originated.
useragentstring
Client user-agent string.
payloadstring
Intent text shown to the user.

Same device

POST /api/v2/identification/same-device · Scope: identification:same · Autostart

Same-device flows run when the user visits your app on the same device as their pasby app. Engage a pasby button or open the returned link.

Body field	Type	Description
`action`	string	`login`, `signup`, or `link`
`claims`	string[]	Claim keys
`payload`	string	User-visible intent

Headers (v2): x-api-key, x-access-secret

First pasby device to pick up the flow owns the session. You cannot target a specific NIN with this scope.

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

201 Created

{
  "status": "successful",
  "reason": "Identification request created",
  "data": {
    "link": "https://open.pasby.africa/app/?mode=identification&id=req_1714661447-NUkY&source=mobile",
    "request": {
      "id": "req_1714661447-NUkY",
      "consumer": "bcn_•••••••",
      "app": "app_•••••••",
      "mode": "identification",
      "action": "signup",
      "user": "",
      "acquireClaims": ["naming.family", "naming.given", "contact.email"],
      "signature": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6InJlcV8xNzE0NjYxNDQ3…",
      "iat": 1714661447,
      "exp": 1714661807,
      "payload": "Create your account with pasby"
    }
  }
}

Response field	Description
`request`	Identification model
`link`	Open on client to start the flow

SampleCode reference: autostart flows.

Wildcard

POST /api/v2/identification/wildcard · Scope: identification:wildcard · Secure start

When the user's NIN is unknown, pasby returns seeds[] — encode one randomly as a QR code. First scan wins; later scans are void.

Body field	Type	Description
`action`	string	`login`, `signup`, or `link`
`claims`	string[]	Claim keys
`seeds`	number	Number of unique flow codes (1–10) for QR rotation
`payload`	string	User-visible intent

Headers (v2): x-api-key only (no secret on wildcard identification).

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": "login",
    "seeds": 4,
    "claims": ["naming.family", "naming.given", "contact.email"],
    "payload": "Identify with pasby"
  }'

201 Created

{
  "status": "successful",
  "reason": "Identification request created",
  "data": {
    "request": {
      "id": "req_1714661500-WcRd",
      "consumer": "bcn_•••••••",
      "app": "app_•••••••",
      "mode": "identification",
      "action": "login",
      "user": "",
      "acquireClaims": ["naming.family", "naming.given", "contact.email"],
      "signature": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…"
    },
    "seeds": [
      "pasby://edbee6303ddcd8d89b6f3052385954b4eb82e7-vi(eb4ae73b5f431deffaeb047cf028e8bc)",
      "pasby://a1b2c3d4e5f6789012345678901234567890ab-vi(cafebabe0123456789abcdef01234567)"
    ]
  }
}

Response field	Description
`request`	Identification model
`seeds`	Shuffle and render as QR codes for scanning

SampleCode reference: secure start flows.

Different device

POST /api/v2/identification/different-device · Scope: identification:another · Direct start

Requires the target user (NIN). pasby pushes the flow to that user's registered devices immediately.

Body field	Type	Description
`user`	string	NIN (min 11 characters)
`action`	string	`login`, `signup`, or `link`
`claims`	string[]	Claim keys
`payload`	string	User-visible intent

Headers (v2): x-api-key, x-access-secret

Some restricted scopes may require pasby approval for certain sectors. Contact support if identification:another is not provisioned for your app.

curl -sS -X POST "https://s.pasby.africa/api/v2/identification/different-device" \
  -H "x-api-key: bk-test_YOUR_KEY" \
  -H "x-access-secret: YOUR_APP_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "login",
    "user": "12345678901",
    "claims": ["naming.family", "naming.given", "contact.email"],
    "payload": "Sign in to your dashboard"
  }'

201 Created

{
  "status": "successful",
  "reason": "Identification request created",
  "data": {
    "request": {
      "id": "req_1714661600-DdEv",
      "consumer": "bcn_•••••••",
      "app": "app_•••••••",
      "mode": "identification",
      "action": "login",
      "user": "12345678901",
      "acquireClaims": ["naming.family", "naming.given", "contact.email"],
      "signature": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…"
    }
  }
}

Poll with flow ping until claims appear, then decrypt.

SampleCode reference: direct start flows.

Identity not on pasby

When the NIN has no linked pasby digital ID:

Handle in your UI — offer signup, wildcard, or alternate onboarding.

400 Bad Request

{
  "status": "failed",
  "reason": "National does not have a pasby™ digital ID"
}

After identification — encrypted claims

Completed flows return encrypted claim maps on ping. Decrypt each field with your app RSA private key before use in your product.

See Handling encrypted claims for a full decrypt walkthrough and SampleCode pasby.ts.

Raw claims (encrypted)

{
  "claims": {
    "contact": {
      "email": "y6l/srG+g/2l2QinsjXxnn4MxY0cTzIDFiRrChjtSIl/LUUkQt8zAUsY4…"
    },
    "naming": {
      "family": "SsF83HO/6g6+Sf+6n0nl3NhSJoEsMYYy5KMuBkIrtH33pD+Lan…",
      "given": "LqDr6DjnleWbPLESTCd8t9ttuwFL4fwiW1R3hS5Q/o/jk/7K8E1P2…"
    }
  }
}

After decryption

{
  "claims": {
    "contact": { "email": "john.doe@example.com" },
    "naming": { "family": "Doe", "given": "John" }
  }
}

For redirect + PKCE, use the OIDC API instead of these REST endpoints.

On this page