Bitcall APIAPI Keys & Secrets
What an API key is, how the secret works, and the key lifecycle.
An API key is the identity your app presents to the gateway. It pairs a public key id with a private secret and carries everything the gateway needs to authorize a request: the tenant it belongs to, its role, and its scopes.
Key id and secret
| Key id | Secret | |
|---|---|---|
| Sent on requests? | Yes, as x-key-id. | Never — used only to sign. |
| Format | ak_<env>_<64 hex> | 128 hex characters. |
| Retrievable? | Always. | Only once, at creation/rotation. |
The secret authenticates every request (Authentication) and is sent as the x-api-secret header. Treat it like a password: store it in a secret manager, never commit it, never put it in client‑side code. Because it travels with each call, prefer keys restricted with an IP allowlist for production.
There is no "reveal secret" endpoint by design — the gateway only stores an encrypted copy it can verify against, not one it can show you. If a secret is lost or leaked, rotate the key.
Environments
The key id prefix tells you the environment:
ak_live_…— production keys.ak_test_…— non‑production keys.
Use test keys in development and CI, and live keys only in production.
What a key carries
Each key is bound to a fixed set of properties, all decided by the admin who mints it:
| Property | Meaning |
|---|---|
Tenant (targetId) | The account the key acts on behalf of. A key can never act on another tenant. |
User (userId) | The principal within the tenant. |
| Role | client, admin, or superadmin — see Permissions. |
| Scopes | The exact product operations the key may call, e.g. otp:read. |
| IP allowlist | Optional. If set, requests from other IPs are rejected. |
| Rate limit | Requests allowed per window — see Rate Limits. |
| Status | active or revoked. |
Lifecycle
- Create — an admin mints the key; the secret is shown once.
- Rotate — mints a replacement key id + secret and revokes the old one. Use this on any suspected leak, or on a routine schedule.
- Revoke — permanently disables a key. Revoked keys fail authentication immediately.
All three are admin operations — see Key Management.
Rotation issues a new key id, not just a new secret. Roll it out by updating both x-key-id and the secret in your app, then revoking the old key once traffic has moved over.