pasbydocs
Concepts

Flows & request IDs

Create, track, and cancel identification and signing journeys.

A flow is the journey between your app starting a request and the user completing or cancelling it.

Lifecycle

  1. Create — POST to identification, signing, or document endpoint.
  2. User action — User completes in pasby app, via deep link, or QR (wildcard).
  3. Observe — POST /api/v2/flow/ping, GET /api/v2/flow/sse, or webhook (for sign).
  4. Terminal — Claims populated, signature present, or cancelled: true.
  5. Cancel (optional) — POST /api/v2/flow/cancel if the user abandons your UI.

Flow identifiers often use the req_ prefix. Store the id from the create response and pass it as request in ping and cancel.

Ping response fields (typical)

FieldNotes
requesterConsumer (organisation) id
requesteeUser NIN when assigned
onsessionUser’s pasby device picked up the flow
cancelledFlow was cancelled
claimsEncrypted object when identification completes
signaturePresent when signing completes
signedAtTimestamp when signature recorded
iatFlow created at (unix)

Encrypted claim strings must be decrypted with your app private key — not read as plain text. See Flow lifecycle for polling intervals, SSE, and sample responses.

Terminology

Key terms used across pasby APIs and documentation.

Device patterns

Same-device, different-device, and wildcard flows for identification and signing.

On this page

LifecyclePing response fields (typical)