Bitcall APIPermissions
Roles, scopes, and how the gateway decides what a key can do.
Authorization has two layers: a key's role (how much authority it has) and its scopes (which product operations it may call). A request must satisfy both.
Roles
Every key has one role. Roles are ranked — a higher role can do everything a lower one can.
| Role | Rank | Scope of authority |
|---|---|---|
client | 0 | A single principal within one tenant. The default for app integrations. |
admin | 1 | Manages its own tenant, including minting client keys for it. |
superadmin | 2 | Cross‑tenant platform authority. |
A route may require a minimum role. For example, a product's administrative endpoints require admin, and platform‑wide settings require superadmin. A key whose role is too low is refused with 401 INVALID_API_KEY, the same answer as any other credential problem.
Scopes
A scope names a product and a kind of operation: <product>:<operation>. The model is
uniform across every product, so there are only two client scopes to think about per
product — and you can tell which one an endpoint needs from its HTTP method.
| Scope | Grants |
|---|---|
<product>:read | Every read. GET requests: status, history, catalogs, results. |
<product>:write | Every change. POST, PATCH, PUT and DELETE requests: purchases, cancellations, refund requests. |
<product>:* | Both of the above for that product (wildcard). |
So a key that only reads the OTP catalog needs otp:read; one that also rents numbers
needs otp:write as well. The same pattern gives esim:read/esim:write and
hlr:read/hlr:write.
Scopes are additive and least‑privilege: a key can only do what it has been explicitly granted (plus what its role implies). Grant the narrowest set that works — prefer otp:read over otp:* when read access is all that's needed.
Administrative and platform scopes (<product>:admin, <product>:super) exist for the
Bitcall panel and are not part of the published API.
Effective permissions
The permissions actually applied to a request — the effective scopes — are computed from several inputs, not just the key's granted list:
- Start from the key's role baseline plus its granted scopes.
- Drop any scope above the key's role tier (a
clientkey can never wield anadmin‑ orsuper‑level scope, even if granted). - Drop scopes for any product feature disabled for the tenant.
- Drop any API explicitly disabled for that user.
So a scope can be present on the key yet not effective — because the product is turned off for your account, or your user is restricted. Either way the answer is 401 INVALID_API_KEY: the reasons are ours, and are not distinguished on the wire. If your credentials are definitely correct, permissions are the thing to check.
How a request is authorized
For a scoped route, the gateway checks, in order:
- Role — the key's role rank meets the route's minimum.
- Feature — the product is enabled for the tenant.
- Scope — the effective scopes include the operation the route requires.
Only if all three pass does the request proceed to rate limiting and proxying.
Changing what a key can do (granting/removing scopes, toggling features, disabling an API for a user) is an admin operation — see Key Management.