API Keys & Secrets

An API key is the identity your app presents to the gateway. It pairs a public key id with a private secret, and it is bound to your account — a key can only ever act as itself.

This page is the concept. To actually issue one, see Get & Manage Keys — you create your own from the Bitcall panel.

Key id and secret

	Key id	Secret
Sent on requests?	Yes, as `x-key-id`.	Yes, as `x-api-secret`.
Format	`ak_<env>_<64 hex>`	128 hex characters.
Retrievable?	Always.	Only once, when the key is issued or rotated.

The secret is what proves a request is yours — see Authentication.

Treat it like a password: store it in a secret manager, never commit it, never put it in client-side code. Because it travels on every request, prefer keys restricted with an IP allowlist in production.

There is no "reveal secret" endpoint by design — the gateway stores only 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 issued with a fixed set of properties:

Property	Meaning
Account	The account the key acts on behalf of. A key can never act on another account.
IP allowlist	Optional. If set, requests from any other address are rejected.
Rate limit	Requests allowed per window — see Rate Limits.
Status	`active` or `revoked`. A revoked key fails immediately.

Which products and operations a key may call is set when it is issued. If a call you expect to work returns 401 INVALID_API_KEY while your credentials are definitely correct, that is the thing to check with whoever issued the key — quote the requestId from the response and it can be confirmed exactly.

Lifecycle

	What happens
Create	The key is issued and the secret is shown once. Capture it then.
Rotate	A replacement key id and secret are issued, and the old key is revoked. Use this on any suspected leak, or on a schedule.
Revoke	The key is permanently disabled and fails authentication at once.

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 confirm traffic has moved over — the old key stops working the moment it is revoked.

Using more than one key

Prefer one key per integration. Separate keys make revoking or rotating one system surgical, instead of an outage for everything that shared a credential.

Note that extra keys do not buy extra throughput: rate limits are counted per user, not per key.