Concepts
Authentication
OAuth 2.0 client credentials, scopes, and how revoking works.
The API uses the OAuth 2.0 client credentials flow, made for servers calling servers. There is no user sign-in and no browser step. Never put the secret in a mobile app or a web page.
The flow
- Create credentials on the website (Developers). You get a client ID and a secret, shown once.
- Send them to
POST /oauth/tokenand receive a bearer token valid for one hour (expires_in: 3600). - Send the token on every call:
Authorization: Bearer <token>. - Before it expires, ask for a new token. Do not ask on every call; cache the token.
You may send the ID and secret in the form body, or as an HTTP Basic header (Authorization: Basic base64(client_id:client_secret)).
Scopes
Credentials carry the scopes you chose. A token can carry the same or fewer, never more. Asking for a scope the credentials do not have answers invalid_scope.
| Scope | Allows |
|---|---|
| balance.read | Read the balance |
| beneficiaries.read | List and read people |
| beneficiaries.write | Add people |
| payouts.read | List and read payout batches |
| payouts.write | Create, submit and cancel batches |
| sandbox.fund | Test mode only: add fake money |
Revoking
Revoke credentials on the website and every token already issued from them stops working at once, not after an hour. Credentials can also be given an expiry when you create them.
Token errors
| error | Status | Meaning |
|---|---|---|
| unsupported_grant_type | 400 | Only client_credentials is supported. |
| invalid_client | 401 | Wrong ID or secret, or the credentials were revoked or expired, or the business is not active. |
| invalid_scope | 400 | You asked for a scope your credentials do not have. |