Authentication

Every request (except the OpenAPI spec and these docs) is authenticated with a partner API key.

Sending your key

Pass your key as a bearer token in the Authorization header:

Authorization: Bearer billy_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

The X-API-Key header is accepted as an alternative if a bearer token is awkward in your stack.

Issuing and revoking keys

Manage keys yourself in the partner dashboard under Developer → API keys. Issue one key per environment or service, so you can revoke a single one without taking everything else down.

Keys are revoked, not deleted — a revoked key stops working at once, but its record remains so you can always reconstruct what was live and when.

How keys are stored

Keys are stored only as a SHA-256 hash. The plaintext is shown to you exactly once at issue time and is never recoverable — not by you, not by us. If a key is lost or compromised, revoke it and issue a new one.

Availability & scope

Your key sees all active billers, plus any strict billers your partner account has been approved for. Deactivated billers and unapproved strict billers are never returned and cannot be quoted or paid.

A key is scoped to your partner account. Payments, refunds, wallets, and webhook deliveries are all filtered to your account — another partner's id returns 404, never someone else's data.

Rate limits

The limit is per partner, not per key — issuing more keys won't raise it. Exceeding it returns 429; back off and retry.

Errors

Full detail, including retry guidance, is on Errors & idempotency.