Developer documentation

Every request authenticates with a secret API key sent as a bearer token. Keys belong to your account, work across every Amarseba service, and all keys of one account debit the same wallet.

Key format

A key is sk-ams-live- or sk-ams-test- followed by 48 random letters and digits. The prefix tells you the mode at a glance and lets secret scanners detect leaked keys. We store only a SHA-256 hash, so a lost key cannot be recovered: create a new one.

sk-ams-live-3fQ9xLmR…(48 characters)
sk-ams-test-Vb82KpZw…(48 characters)

Sending the key

Send the key in the Authorization header on every request. The API never reads cookies or sessions.

Authorization: Bearer sk-ams-live-…

• Never put a key in a query string or URL: URLs end up in logs, proxies and browser history.
• Never ship a key to a browser or mobile app. Call the API from your server and keep the key server-side, in an environment variable or secret manager.
• Use a separate key per platform (ERP, website, mobile back end) so you can revoke one without touching the others.

Scopes

A key can only call endpoints its scopes allow. Grant the smallest set each integration needs. A missing scope returns 403 insufficient_scope with the scope it needed in data.required_scope.

IP allowlist

Optionally restrict a key to your servers' addresses. Each entry is a single IPv4 or IPv6 address or a CIDR range such as 203.0.113.0/24. A key without an allowlist accepts requests from any address. A request from any other address returns 403 ip_not_allowed with the caller's address in data.ip.

Expiry

A key can carry an optional expiry date. After it passes, requests return 401 api_key_expired with data.expired_at. Keys expiring within seven days are highlighted on the API Keys page.

Rotation

Rotating a key issues a new secret for the same key. Its key ID, name, mode, scopes, IP allowlist and expiry stay as they are, so nothing else in your integration changes. Rotate from the API Keys page with Rotate key; the new secret is shown once, like a freshly created key.

The previous secret keeps working for 24 hours after the rotation, so you can deploy the new one without downtime. The key shows a Rotating badge during that window. Once it passes, the previous secret returns 401 invalid_api_key. Only one previous secret is ever valid: rotating again inside the window ends the older secret immediately.

1. Rotate the key and copy the new secret.
2. Deploy the new secret to every server that uses the key.
3. Verify that requests succeed with the new secret, for example with GET /api/v1/wallet/balance.
4. Let the old secret lapse on its own when the window ends.

If a secret has leaked, revoke the key instead. Revoking stops both secrets immediately and returns 401 api_key_revoked; create a new key to replace it. Revoked or expired keys cannot be rotated.

Authentication errors