Authentication
API keys, the permissions they hold, how to keep them safe, and the 401 and 403 answers.
Send your API key
Every request carries an API key as a bearer token:
curl "$APEX_BASE_URL/v1/balances" \
-H "Authorization: Bearer $APEX_API_KEY"A key looks like ak_test_ (sandbox) or ak_live_ (production), followed by an 8-character prefix, an underscore and a 52-character secret. Send exactly one Authorization header: a key sent beside a second one is refused.
Keep keys on your servers
An API key acts for your whole account within its permissions. Use it only from your back end, never in a browser, a mobile app or a repository. Keep it in a secret store and out of logs.
Create a key
API keys are created in the Customer panel, not through the API. A person with the Customer admin role opens API keys, chooses Create key and sets:
| Field | What it does |
|---|---|
| Name | What uses the key, such as "ERP sync". |
| Permissions | What the key may do. At least one; see below. |
| Allowed addresses | Optional. IP addresses or CIDR ranges the key may be used from. Empty allows any address. |
| Expires on | Optional. The key stops working at the end of that day (UTC). |
The key is shown once, when it is created. If it is lost, revoke it and create a new one. An account holds at most 25 keys that are not revoked.
The panel lists every key with its state (active, expired or revoked), its permissions, its allowed addresses and when it was last used.
Permissions
Give each key only what its system needs.
| Permission | In the panel | Unlocks |
|---|---|---|
customer:read | Read balances, payouts and beneficiaries | Every read: GET /v1/customer, /v1/balances, /v1/payouts, /v1/incoming-payouts, /v1/beneficiaries, /v1/receiving, /v1/deposit-instructions, /v1/onboarding, /v1/terms, /v1/end-customers |
customer:payouts:create | Create and cancel payouts | POST /v1/quotes, POST /v1/payouts, POST /v1/payouts/{id}/cancel |
customer:beneficiaries:write | Register beneficiaries | POST /v1/beneficiaries, POST /v1/beneficiaries/link, POST /v1/receiving/code, PUT /v1/receiving/account |
customer:webhooks:manage | Manage webhooks | Every /v1/webhooks route: register, disable, enable, rotate the secret, read deliveries, redeliver |
customer:profile:write | Complete KYC or KYB | /v1/profile, /v1/documents, POST /v1/terms |
customer:end_customers:manage | Manage End Customers | POST /v1/end-customers and its suspend and reactivate actions (Platforms only) |
A key never holds these, whoever creates it:
customer:payouts:approve: approving or rejecting a held Payout is a person's decision, made in the Customer panel. A Payout a key creates can wait inawaiting_approvaluntil someone approves it.customer:rules:manage: approval rules are edited in the panel.customer:keys:manageandcustomer:team:manage: a key never creates keys or manages people.
Allowed addresses
With allowed addresses set, a request from any other address is refused with api_key_ip_denied. List the public addresses your requests leave from, one IP or CIDR range per entry (up to 50), for example 203.0.113.7 or 198.51.100.0/24. IPv4 and IPv6 both work.
Expiry and revocation
An expired key is refused with api_key_expired. Revoke a key in the panel at any time; it is refused from that moment on, and revoking cannot be undone.
A key is also revoked when the person who created it is disabled in the Customer panel. Create the keys your production systems depend on from an admin account that will stay, and plan a rotation when someone leaves.
Rotate keys
There is no rotate call: rotate by overlap.
- Create a new key with the same permissions and allowed addresses.
- Deploy it to your systems.
- Check in the panel that the old key's "Last used" has stopped moving. It is refreshed about once a minute.
- Revoke the old key.
Rotate on a schedule, when someone with access to the key leaves, and at once if a key may have leaked.
When a request is refused
Authentication failures answer 401; a key that is valid but may not do this answers 403. Both use the error envelope.
| Status | Code | Meaning |
|---|---|---|
| 401 | unauthorized | No Authorization header, or a bearer token that is not an API key. |
| 401 | api_key_invalid | The key is unknown, malformed, from the other environment or revoked, or it came with a second Authorization header. The answer does not say which, on purpose. |
| 401 | api_key_expired | The key's expiry has passed. |
| 401 | api_key_ip_denied | The request came from an address outside the key's allowed addresses. |
| 401 | api_key_revoked | The key was revoked. You usually see api_key_invalid instead. |
| 403 | forbidden | The key lacks the permission this route needs. |
| 403 | customer_suspended | Your account is suspended. Reads still work; changes are refused, except disabling webhook endpoints and suspending End Customers. |
| 403 | customer_not_active | Your account is not active (still being onboarded, or closed). |
| 403 | not_for_end_customers | An End Customer's webhook endpoints are its Platform's. |
| 403 | people_only | Only a person may do this, such as inviting an End Customer's first user. |
{
"code": "api_key_ip_denied",
"message": "the API key may not be used from this address",
"correlation_id": "4a7e2c91-0b5d-4f38-9e16-8c3d2a1f7b05"
}