Aesesdocs

Authentication

The Aeses API uses secret keys to authenticate requests. Every request must include your key in the x-api-key header. There is no OAuth flow — Aeses is a server-to-server API designed to be called from your backend.

Sending the key

Authenticated request
curl https://api.aeses.io/v1/balances \
-H "x-api-key: sk_live_..."

All requests must be sent over HTTPS. Plain HTTP requests fail TLS termination before reaching the API. Requests without an x-api-key header, or with a malformed key, return 401 authentication_error.

Key formats

| Prefix | Environment | Use | | ----------- | ----------- | --------------------------------------------------------------------- | | sk_test_… | Test mode | Public test networks. Never moves real funds. Use during development. | | sk_live_… | Live mode | Production networks. Authorizes real value movement. |

A sk_live_ key cannot read sk_test_ data, and vice versa. The two environments are fully isolated — see Environments for details.

Creating and rotating keys

Manage keys from the Dashboard → Developers → API keys. You can:

  • Create any number of keys per environment. Name each one for the system that uses it (e.g. checkout-prod, reconciliation-worker).
  • Rotate by creating a new key, deploying it everywhere, then revoking the old one. Aeses does not impose a hard cutover — revoke whenever your rollout is complete.
  • Revoke instantly. A revoked key returns 401 authentication_error on every subsequent request.
Revoke compromised keys immediately

If a secret key is exposed in a log, repository, or screenshot, revoke it from the dashboard right away and replace it. There is no recovery path that does not require revocation.

Storing keys safely

  • Read the key from an environment variable or a secrets manager (AWS Secrets Manager, HashiCorp Vault, GCP Secret Manager). Do not hardcode it.
  • Never ship a secret key in browser, mobile, or desktop client code. If a client needs to initiate a payment, generate a short-lived charge object server-side and pass the charge ID to the client.
  • Avoid logging the full key. If you must log it for debugging, log only the last four characters.

Errors

| Status | Code | Cause | | ------ | -------------------------- | -------------------------------------------------------- | | 401 | authentication_error | Missing, malformed, revoked, or expired key. | | 401 | key_environment_mismatch | A sk_test_ key was used against a live-only resource. | | 403 | forbidden | The key is valid but lacks permission for this resource. |

See Errors for the full error model.