API reference
Authentication
v2 API key + app secret and legacy v1 bearer tokens.
Authenticate every public API request with headers from the pasby console. v2 (universal authentication) uses API key + app secret on each call. v1 uses authorize + x-access-token for legacy apps.
Credential types
| Header | Role |
|---|---|
x-api-key | Organisation API key (bk-test_ / bk-live_) — required on nearly all routes |
x-access-secret | App secret from Console — primary credential for v2 |
x-access-token | Session token — v1 legacy (from authorize response header) |
Routes that require the secret at the gateway return HTTP 400 with plain text:
App secret missing in headers.Missing API key returns HTTP 401:
An api key is needed to access our services.v2 — Universal authentication (recommended)
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": "req_YOUR_FLOW_ID" }'There is no v2 authorize endpoint. Configure official SDKs with API key + secret (SDKs).
v1 — Basic authentication (legacy)
- Call authorize (save
x-access-tokenfrom response headers, not the JSON body):
curl -sS -i "https://s.pasby.africa/api/v1/flow/authorize?sub=YOUR_CONSUMER_ID&app=YOUR_APP_ID" \
-H "x-api-key: bk-test_YOUR_KEY" \
-H "x-access-secret: YOUR_APP_SECRET"- Pass the token on subsequent calls:
curl -sS -X POST "https://s.pasby.africa/api/v1/flow/ping" \
-H "x-api-key: bk-test_YOUR_KEY" \
-H "x-access-token: YOUR_BEARER_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "request": "req_YOUR_FLOW_ID" }'| Authorize error | Status | Body |
|---|---|---|
| Missing secret | 401 | App secret missing |
| Missing consumer | 403 | Forbidden request. No consumer provided. |
Missing app when sub set | 400 | Authorization grants are only given to apps not organizations. |
Header matrix
| Category | v2 headers | v1 headers |
|---|---|---|
| Health / root | x-api-key | x-api-key |
| Identification same-device | x-api-key, x-access-secret | x-api-key, x-access-secret |
| Identification different-device | x-api-key, x-access-secret | x-api-key, x-access-token |
| Identification wildcard | x-api-key | x-api-key, x-access-token (recommended) |
| Signing same-device | x-api-key, x-access-secret | x-api-key, x-access-secret, x-access-token |
| Signing different-device | x-api-key, x-access-secret | x-api-key, x-access-token |
| Signing wildcard | x-api-key, x-access-secret | v2 only |
| Flow authorize | — | x-api-key, x-access-secret + sub, app query |
| Flow ping / cancel | x-api-key, x-access-secret | x-api-key, x-access-token |
| Flow SSE | x-api-key (secret optional) | v2 only |
| Flow polling | x-api-key, x-access-token | Same (even on v2 route) |
| Document signing / review / refresh | x-api-key, x-access-secret | x-api-key, x-access-token |
Always send x-api-key and x-access-secret on v2 document calls (signing, review, refresh).
Security
- Never commit API keys or secrets to git or ship secrets in client-side code.
- Pair sandbox keys with sandbox secrets and live keys with live secrets.
- See Credentials & environments for prefixes and communication keys.