Identification

Base path: /api/v2/identification · Billing: authentication

POST /api/v2/identification/same-device

Headers: x-api-key, x-access-secret

Field	Type	Required
`payload`	string	Yes
`action`	string	Yes — `login`, `signup`, `link`
`claims`	string[]	Yes

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 '{
    "payload": "session-abc-123",
    "action": "login",
    "claims": ["naming.given", "naming.family", "contact.email"]
  }'

POST /api/v2/identification/different-device

Headers: x-api-key, x-access-secret

Field	Type	Required
`user`	string	Yes — NIN, min 11 chars
`payload`	string	Yes
`action`	string	Yes
`claims`	string[]	Yes

Response may set x-access-token when the backend returns a token in data.

POST /api/v2/identification/wildcard

Headers: x-api-key

Field	Type	Required
`payload`	string	Yes
`action`	string	Yes
`seeds`	number	Yes — 1–10
`claims`	string[]	Yes

Non-existent identity

If user (NIN) is not registered with pasby, different-device may return HTTP 400 with validation errors. Handle in UI and offer signup or wildcard flows.

TypeScript SDK

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

const pasby = new Pasby({ apikeyAuth: "…", appSecretKey: "…", basePath: "https://s.pasby.africa" });

await pasby.identification.sameDevice({ action: "login", claims: ["naming.given"], payload: "…" });
await pasby.identification.differentDevice({ action: "login", user: "12345678901", claims: ["…"], payload: "…" });
await pasby.identification.wildcard({ action: "signup", seeds: 4, claims: ["…"], payload: "…" });

See TypeScript / Node.js SDK.

Guides

Full request/response walkthroughs: Identification guide.

Legacy v1

Mirror paths under /api/v1/identification/:

Suffix	v1 headers
`same-device`	`x-api-key`, `x-access-secret`
`different-device`	`x-api-key`, `x-access-token`
`wildcard`	`x-api-key`, `x-access-token` (recommended)

Responses echo version: "v1". See Migration.