API overview · pasby docs

Production: https://l.pasby.africa · Sandbox: https://s.pasby.africa

The public API is available at https://l.pasby.africa (production) and https://s.pasby.africa (sandbox). Use v2 for all new integrations.

Versioning

Version	Path	Recommendation
v2	`/api/v2/...`	Use for all new integrations
v1	`/api/v1/...`	Legacy only — Migration

Unversioned: GET /, GET /api/health/check.

Global platform behavior

Behavior	Detail
Content-Type	`application/json` on POST bodies; SSE returns `text/event-stream`
CORS	Enabled on API routes
Rate limit	100 requests / minute / IP — HTTP `429` with plain-text body
Usage metering	Calls with `x-api-key` and HTTP status below 500 are recorded asynchronously
Billing gate	Identification → `authentication` billing; signing & document → `signature` billing. `bk-test_` keys skip pre-check
IP forwarding	Client IP from `cf-connecting-ip`, then `x-real-ip`, then `x-forwarded-for`

API keys

Prefix	Environment	Billing pre-check
`bk-test_`	Sandbox (`s.pasby.africa`)	Skipped
`bk-live_`	Production (`l.pasby.africa`)	Enforced

See Credentials & environments.

Response envelope

{
  "status": "successful",
  "reason": "Human-readable summary",
  "cost": 0.5,
  "version": "v2",
  "data": {}
}

Field	Description
`status`	Outcome (`successful`, `handled`, etc.)
`reason`	Human-readable message
`cost`	Optional operation cost
`version`	`v1` or `v2` echoed by the gateway
`data`	Operation-specific payload (backend-defined)

Response headers

Header	When
`x-access-token`	v1 authorize grant; v2 different-device identification when backend returns a token in `data`

Resource map

Domain	Base path	Billing
Identification	`/api/{version}/identification`	authentication
Signing	`/api/{version}/signing`	signature
Flow	`/api/{version}/flow`	none
Document	`/api/{version}/document`	signature

Sections

Authentication — headers by endpoint category
System — health and connectivity
Identification — same / different / wildcard
Signing — sign and confirm (dynamic schema)
Flows — ping, SSE, cancel, polling, authorize (v1)
Documents — signing, review, refresh

Endpoint index — full route table.

TypeScript SDK

Server-side Node integrations should use @finsel-dgi/pasby. Each namespace maps to the routes above (pasby.identification, pasby.signing, pasby.flows, pasby.docs, pasby.health).