Credentials & environments
API keys, app secrets, sandbox vs production, and required headers for v2.
Environments
| Environment | Base URL | API key prefix | Billing pre-check |
|---|---|---|---|
| Sandbox | https://s.pasby.africa | bk-test_ | Skipped |
| Production | https://l.pasby.africa | bk-live_ | Enforced |
Obtain keys and secrets from the pasby console. Step-by-step setup with Console screenshots: How to get API keys. Pair test keys with test secrets and live keys with live secrets—mixing environments returns credential errors.
Typical secret prefixes: snb_ (sandbox), prd_ (production). Confirm exact formats in Console when you create an app.
Console overview
Console is where you manage organisations, apps, API keys, client secrets, communication keys, scopes, and usage. Typical workflows:
| Area | What you do |
|---|---|
| Organisations | Billing boundary; one org can host multiple apps |
| Apps | Per-product integration; each has its own client secret and PEM keys |
| API configuration | Generate organisation API keys (bk-test_ / bk-live_) |
| App settings | Client ID, secrets, communication / service account files |
Organisations and apps
An organisation (consumer) groups apps that share billing. When you register, your first organisation is usually created for you. You can add more from the dashboard.
An app belongs to exactly one organisation. It uses the organisation’s API key but has its own app secret and RSA communication keys for decrypting claims. Each app is either Sandbox or Production — not both at once.
Credential prefixes
| Prefix | Meaning |
|---|---|
bcn_ | Consumer (organisation) id |
app_ | Application id |
bk-test_ / bk-live_ | API key (sandbox / production) |
snb_ / prd_ | App secret (typical; confirm in Console) |
Setup checklist
Follow the full walkthrough in How to get API keys, then continue with Your first call.
Production access requires a billing plan; see pasby pricing.
Credential headers
| Header | Role |
|---|---|
x-api-key | Your organisation API key — required on nearly all endpoints |
x-access-secret | Your app secret — primary credential for v2 |
x-access-token | Session token — v1 legacy only |
v2 (recommended)
x-api-key: bk-test_your_api_key
x-access-secret: your_app_secret
Content-Type: application/jsonRoutes that require the secret return HTTP 400 with plain text App secret missing in headers. if it is absent.
v1 (legacy)
- Call
GET /api/v1/flow/authorizewith secret, API key, and query params. - Store the
x-access-tokenresponse header. - Pass
x-access-tokenon subsequent calls.
Migrate to v2 to remove the authorize + token lifecycle. See Migration v1 → v2.
Communication keys
Backend apps need RSA key pairs to decrypt claims returned from flow ping after identification.
- Open your app in the pasby console.
- Download the communication / service PEM files for your environment.
- Store the private key on your server only.
Walkthrough: Handling encrypted claims. Reference decrypt helper: SampleCode pasby.ts.
Security rules
- Never commit secrets to git or expose them in client-side code.
- Rotate secrets via Console when team members leave or keys leak.
- Log request IDs, not secrets or full access tokens.
- Treat every call with a valid API key as metered (including health checks).
Global platform behavior
| Behavior | Detail |
|---|---|
| CORS | Enabled on API routes |
| Rate limit | 100 requests / minute / IP — HTTP 429 if exceeded |
| Usage metering | Requests with x-api-key and status below 500 are recorded |
| Billing gate | Identification routes check authentication billing; signing and document routes check signature billing (skipped for test keys) |