Authentication
Secret API keys, scopes, rotation and how TeePay authorises every request.
TeePay authenticates your server with a secret API key sent as a bearer token.
curl https://api.teepay.me/v1/whoami \
-H "Authorization: Bearer tp_live_xxxxxxxx.xxxxxxxxxxxxxxxx"- Header
- Exactly one Authorization: Bearer header
- Live keys
- tp_live_<prefix>.<secret>
- Test keys
- tp_test_<prefix>.<secret>
- Not accepted
- Query-string keys, X-API-Key, keys in the body
Create and manage keys
Keys are created in Developers → API keys in the dashboard. Creating, rotating or revoking a key asks you to confirm the action. The secret is displayed once; TeePay stores only a verifier.
- Expiry: optional, up to 366 days.
- Rotation: issues a new secret and keeps the old one working for an overlap you choose (1 second to 1 hour), so you can deploy without downtime.
- Revocation: takes effect immediately. Revoke at once if a key may have leaked.
Scopes
Each key carries the scopes you select. A scope only works while your account also has the matching permission, so removing a permission from your account disables the scope immediately.
| Scope | Allows |
|---|---|
collection:read | Read collections and their status |
collection:create | Send mobile money push payments |
checkout:read | Read checkout sessions |
checkout:create | Create checkout sessions |
control_number:read | Read Control Numbers and their verified payments |
control_number:create | Issue Control Numbers (requires approved Control Number access) |
disbursement:read | Read payouts |
disbursement:create | Quote and send payouts (requires payout approval) |
GET /v1/whoami and GET /v1/capabilities work with any valid key.
How each request is authorised
- The key is verified and must be active, unexpired and match the environment.
- Your application and account must be active and verified, and not suspended.
- The endpoint's scope must be on the key and permitted for your account now.
- Rate limits are applied per key and per application.
The account a request acts for always comes from the key. No endpoint accepts a merchant or account ID in the body, so a key can never act for another business.
Keep keys on your server
API keys grant access to your money. Never put them in a website, mobile app, chatbot prompt or public repository. For AI agents use the restricted link key instead.