Skip to Content
Apex Settlement

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
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:

FieldWhat it does
NameWhat uses the key, such as "ERP sync".
PermissionsWhat the key may do. At least one; see below.
Allowed addressesOptional. IP addresses or CIDR ranges the key may be used from. Empty allows any address.
Expires onOptional. 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.

PermissionIn the panelUnlocks
customer:readRead balances, payouts and beneficiariesEvery 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:createCreate and cancel payoutsPOST /v1/quotes, POST /v1/payouts, POST /v1/payouts/{id}/cancel
customer:beneficiaries:writeRegister beneficiariesPOST /v1/beneficiaries, POST /v1/beneficiaries/link, POST /v1/receiving/code, PUT /v1/receiving/account
customer:webhooks:manageManage webhooksEvery /v1/webhooks route: register, disable, enable, rotate the secret, read deliveries, redeliver
customer:profile:writeComplete KYC or KYB/v1/profile, /v1/documents, POST /v1/terms
customer:end_customers:manageManage End CustomersPOST /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 in awaiting_approval until someone approves it.
  • customer:rules:manage: approval rules are edited in the panel.
  • customer:keys:manage and customer: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.

  1. Create a new key with the same permissions and allowed addresses.
  2. Deploy it to your systems.
  3. Check in the panel that the old key's "Last used" has stopped moving. It is refreshed about once a minute.
  4. 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.

StatusCodeMeaning
401unauthorizedNo Authorization header, or a bearer token that is not an API key.
401api_key_invalidThe 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.
401api_key_expiredThe key's expiry has passed.
401api_key_ip_deniedThe request came from an address outside the key's allowed addresses.
401api_key_revokedThe key was revoked. You usually see api_key_invalid instead.
403forbiddenThe key lacks the permission this route needs.
403customer_suspendedYour account is suspended. Reads still work; changes are refused, except disabling webhook endpoints and suspending End Customers.
403customer_not_activeYour account is not active (still being onboarded, or closed).
403not_for_end_customersAn End Customer's webhook endpoints are its Platform's.
403people_onlyOnly a person may do this, such as inviting an End Customer's first user.
401 Unauthorized
{
  "code": "api_key_ip_denied",
  "message": "the API key may not be used from this address",
  "correlation_id": "4a7e2c91-0b5d-4f38-9e16-8c3d2a1f7b05"
}

On this page