Authentication

Every request to a /v1/* endpoint is authenticated with two headers: your key id and your secret, both sent as-is. There is nothing to compute, sign, or time — a request you write once keeps working.

Required headers

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

Each header must be single-valued. A duplicate or array-valued header is ignored, which then reads as if it were absent.

That is the whole scheme. It works identically from curl, Postman, a browser, or any language.

const res = await fetch('https://api.bitcall.io/v1/esim/plans?region=Europe&pageSize=50', {
  headers: {
    'x-key-id': process.env.KEY_ID,
    'x-api-secret': process.env.SECRET,
  },
});

A POST adds only a body and its content type:

const res = await fetch('https://api.bitcall.io/v1/esim/orders', {
  method: 'POST',
  headers: {
    'x-key-id': process.env.KEY_ID,
    'x-api-secret': process.env.SECRET,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ planId: 'pln_…' }),
});

Keeping your secret safe

Because the secret travels on every request, it reaches anything that records request headers — reverse-proxy access logs, APM traces, WAF captures, your own shell history. Nothing binds the credential to a particular path or body, so a secret read out of a log is enough to call anything your key can call.

Two controls carry the weight:

• Use an IP allowlist. A key restricted to your servers' addresses is useless to anyone who reads the secret out of a log somewhere else. Set one when you create the key in your panel — see Get & Manage Keys. It narrows where a stolen secret can be used, not whether it works: a request from an allowlisted address is accepted whoever sends it, so it does not protect you against a leak on — or a foothold inside — one of those hosts.
• Rotate on any suspicion. Rotation is immediate and has no overlap window: a new key id and secret are issued and the old key stops authenticating at once, so calls still carrying the old credential fail until you deploy the new one. On a suspected leak that gap is worth taking. For a planned credential change, deploy a second key first and revoke the old one afterwards instead — see Rotating a key.

Keep the secret on a server you control. A request made from a browser or a mobile app ships the secret to the device, where any user can read it.

Using the interactive reference

Each API reference page can send real requests with your own credentials. What happens to them is worth knowing before you paste anything in:

• They are held in the page's memory only — no localStorage, no sessionStorage, no cookie — and are discarded when you close or reload the tab.
• They are not sent only to the gateway. Every request goes through this documentation site's own server, which relays it upstream; the gateway sends no CORS headers, so a direct call from your browser would be blocked. That server receives your credential in transit. It stores no copy and writes none to its logs, but it does see it.
• Requests are real. A purchase there charges your account exactly as it would from your own code, so each mutating call asks you to confirm first.

Prefer a key issued for a non-production environment here, and confirm with your provider what that environment actually costs — see Environments and billing.

What the gateway checks, in order

Any failure stops the request immediately — it is never forwarded to a product:

1. Both headers present. Missing credentials → 401 AUTHENTICATION_REQUIRED.
2. Key id is known and active.
3. Source IP is allowed, if the key has an IP allowlist.
4. Secret matches, compared in constant time.
5. Account is in good standing.
6. The product is enabled for your account and your key may call this endpoint.
7. Rate limit not exceeded — see Rate Limits.
8. The request is well-formed. Path, query and body are checked against the endpoint's schema. A bad request → 400 VALIDATION_ERROR, with fields naming what was wrong.