Flow endpoints

Base path: /api/{version}/flow · No billing pre-check on flow routes.

After starting identification or signing, use these endpoints to observe or cancel the journey. See Flow lifecycle.

SDK: pasby.flows.ping, pasby.flows.cancel — not pasby.flow. SSE and polling are REST-only — TypeScript SDK.

POST /api/v2/flow/ping

Client-controlled status poll (recommended).


Headers	`x-api-key`, `x-access-secret`
Body	`{ "request": "<flow-id>" }` — required in practice (edge Zod schema is empty)

curl -sS -X POST "https://s.pasby.africa/api/v2/flow/ping" \
  -H "x-api-key: bk-test_YOUR_KEY" \
  -H "x-access-secret: YOUR_APP_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "request": "your_flow_request_id" }'

Poll every 1–3 seconds; back off when idle. Terminal states include cancelled or a truthy signature in data.request (signing flows).

GET /api/v2/flow/sse (v2 only)

Server-Sent Events stream (~every 2 seconds).


Headers	`x-api-key` (secret optional)
Query	`request=<flow-id>`
Response	`Content-Type: text/event-stream` — `data: {json}\n\n`

curl -N "https://s.pasby.africa/api/v2/flow/sse?request=your_flow_request_id" \
  -H "x-api-key: bk-test_YOUR_KEY" \
  -H "x-access-secret: YOUR_APP_SECRET"

Use with the browser EventSource API for live web UIs.

POST /api/v2/flow/cancel


Headers	`x-api-key`, `x-access-secret`
Body	`{ "request": "<flow-id>" }`

curl -sS -X POST "https://s.pasby.africa/api/v2/flow/cancel" \
  -H "x-api-key: bk-test_YOUR_KEY" \
  -H "x-access-secret: YOUR_APP_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "request": "your_flow_request_id" }'

Call when the user abandons your UI.

POST /api/v2/flow/polling (legacy)

Long-held connection; server polls upstream every ~1.2s. Completes when data.request.cancelled is true or data.request.signature is present.


Headers	`x-api-key`, `x-access-token` (required even on the v2 route)
Body	`{ "request": "<flow-id>" }`

Uses in-process state — not ideal for horizontally scaled deployments. Prefer ping or SSE for v2.

GET /api/v1/flow/authorize (v1 only)

Obtain x-access-token for token-based v1 integrations.

Query	Required
`sub`	Consumer id
`app`	App id when `sub` is set

curl -sS -i "https://s.pasby.africa/api/v1/flow/authorize?sub=YOUR_CONSUMER&app=YOUR_APP" \
  -H "x-api-key: bk-test_YOUR_KEY" \
  -H "x-access-secret: YOUR_APP_SECRET"

v1 flow mirror

Endpoint	v1 headers
`POST /api/v1/flow/ping`	`x-api-key`, `x-access-token`
`POST /api/v1/flow/cancel`	`x-api-key`, `x-access-token`
`POST /api/v1/flow/polling`	`x-api-key`, `x-access-token`

No v1 SSE route.