Get & Manage Keys

You issue your own keys from your panel — there is nothing to request and nobody to wait for. This page walks you from a panel account to a working key, then through managing it afterwards.

For what a key is — key id versus secret, environments, what a key carries — see API Keys & Secrets. This page is the how-to.

curl 'https://api.bitcall.io/v1/otp/countries' \
  --header 'x-key-id: ak_test_1a2b…' \
  --header 'x-api-secret: 9f83…'

Your key list

Once you have keys, the page lists them:

You can narrow the list by Status and by scope, and the table pages once you have more than ten keys. Last used is a coarse signal, not an audit trail: the gateway stamps it at most once a minute per key, and the write is best-effort — it is skipped rather than retried if it fails, so a key that served traffic can still show an older time. It is good for spotting a key nothing calls any more; it is not a way to confirm a deployment has picked up a new credential. Use your own application logs for that.

Rotating a key

Rotation replaces a key with a fresh one. It has no overlap window, so which of the two procedures below you want depends on whether you are reacting to a compromise or doing planned maintenance.

Click the rotate icon on the key's row and confirm in the Rotate this key? dialog. What happens:

1. A new key id and a new secret are issued, carrying over the key's scopes, IP allowlist, rate limit, label and — if it had one — its original expiry date. Rotation is not a way to extend a key's lifetime.
2. The old key is revoked immediately — it stops authenticating the moment you confirm.
3. The new secret is shown once, in the same one-time dialog as at creation.

Suspected compromise — rotate now, accept the gap

If you think a secret has leaked, rotate immediately. The new pair does not exist until you confirm and the old key dies at that same moment, so there is no instant when both work: every call still carrying the old credential fails from then until your deployment ships the new one. That gap is the price of cutting off whoever else holds the secret, and it is the right trade — take the failing requests.

Keep it short: capture the new pair from the dialog, deploy both values together, and confirm the dialog only when someone is ready to deploy — not hours ahead.

Planned change — deploy a second key first, then revoke

For scheduled maintenance there is no reason to accept a gap. Do not use rotate.

1. Create a second key with the same scopes and IP allowlist.
2. Deploy it, so your application is calling with the new credential.
3. Confirm the old key has gone quiet — from your own application logs, not from the Last used column, which is too coarse for this (see Your key list).
4. Revoke the old key.

Two keys can be active at once, which is what makes this seamless where your panel offers key creation. If self-service creation is not enabled for your account, this procedure is not available to you and rotation with its gap is the only route — ask your provider whether they can issue the second key for you.

Revoking a key

Click the revoke icon and confirm in the Revoke this key? dialog. The key stops authenticating at once, permanently — there is no undo, and anything still using it starts failing immediately.

Rotate and revoke are both disabled on a key that is already revoked.

Environments and billing

The key id starts with ak_live_ or ak_test_. That prefix records which environment the key was issued for, and it is useful for telling two credentials apart in your configuration.

So before the first call that could cost you something, get these from your provider and keep them with your credentials:

Treat anything you have not confirmed as live and billable. The paid endpoints publish no idempotency key, so a call you did not mean to make cannot be undone by repeating it — see Conventions.

Rate limits

Above the list, your panel shows your account rate limit — for example 1000 requests / 60s.

That quota is your account's, and every key you hold spends from the same allowance. Two keys do not get you twice the requests — they get you two credentials sharing one allowance. Issuing more keys is a way to separate your integrations, not a way to buy throughput. If you need a higher limit, ask your provider; more credentials will not give you one.

See Rate Limits for what happens when you exceed it.

When a call is rejected

A 401 with error.code set to INVALID_API_KEY covers several situations deliberately, so work through them in order:

Sending no credentials at all is the one case that differs: that returns 401 AUTHENTICATION_REQUIRED.

If you get 400 VALIDATION_ERROR instead, your key was accepted: credentials are checked before the request itself. Fix the fields named in error.fields.

Best practices

• One key per integration. Separate keys make revoking or rotating one system surgical instead of an outage for everything that shared a credential.
• Grant the narrowest scopes that work. A key that only reads cannot be used to spend money. Add :write only where the integration genuinely writes.
• Set an IP allowlist on production keys. It is checked before the secret is verified, so a leaked key is unusable from any address you have not listed. It cannot help when the leak comes from inside that range — revoking the key is what ends that — so treat it as narrowing the blast radius, not closing it.
• Test keys in development and CI, live keys only in production. The ak_test_ / ak_live_ prefix tells you which credential you are holding — not whether calling it is free. Confirm that separately with your provider; see Environments and billing.
• Rotate on any suspicion, and on a schedule. Rotation is cheap; an unnoticed leak is not.
• Never ship a secret in client-side code. Anything sent to a browser or mobile app is readable by whoever holds the device.