Authentication
An API token is a secret string that lets a program use the IBEE API on your organization’s behalf. It works like a key card: it opens only the products and workspaces you chose when you made it, until it expires or you revoke it. You send it with every request in the Authorization header as a Bearer token (“whoever bears this token may make this call”).
When to use an API token
IBEE has four kinds of credentials. They are all created under Organization → API Tokens, one tab each, and they are not interchangeable:
An API token can’t be used in place of an S3 credential or a registry access token. It can create them through the API once Object Storage and Container Registry management resumes; until then, create them in the portal.
How it works
- You create the token in the portal and choose its permissions (which products, read or edit), its access policy (which workspaces) and its expiration.
- Your program sends
Authorization: Bearer <token>with every request. - On each request the API gateway checks, in this order: the token exists and matches; it isn’t revoked, disabled or expired; the request has a
workspace_id; the token has the scope the endpoint needs; the token may use that workspace; and the token’s creator is still an active member of the organization with access. The first check that fails is the error you get.
Before you begin
- Role: only an organization owner or administrator can open Organization → API Tokens. Other members see “Organization API tokens unavailable”.
- Identity verification: until verification is complete, the create button shows Verify Identity and opens the verification page instead. See Verify your identity.
- Know what the token is for: which products it must read or change, and which workspaces. Give it no more than that.
Create an API token
Open API Tokens
In the portal sidebar, under Organization, click API Tokens. The API Tokens tab lists your tokens with their Access, Permissions, Created, Last Used and Status.
Name it
Enter a Name (required, at most 100 characters), for example “Production automation”. Name it after the program that will use it, so you know what breaks if you revoke it.
Choose an access policy
Under Access policy, pick:
- Entire Organization (the default): the token works in every workspace, including ones created later.
- Specific Workspaces: pick one or more workspaces from the list. Each one shows its ID. Requests for any other workspace are refused with
403 workspace_not_allowed.
Set permissions
Under Permissions, each product has a Read and an Edit button. Read lets the token list and view; Edit lets it create, change and delete, and turns on Read too. Select at least one. The scopes each button grants are in the table below.
The new token appears in the list with status Active. Last Used fills in after its first request.
IBEE keeps only a fingerprint of the token, so nobody can show it to you again. If you lose it, revoke it and create a new one.
Use your token
Send it in the Authorization header, with the workspace in workspace_id:
This call needs the Virtual Machines → Read permission (vm.read). A 200 OK with a sites list means the token works.
Tokens look like ibee_prod_key_<id>.<secret>. A production token starts with ibee_prod_key_ and works only at https://api.ibee.ai/v1; a development token starts with ibee_dev_key_ and works only at https://api.ibee.co.in/v1. Sent to the other environment, either one is refused with 401 invalid_api_key.
The SDKs, CLI and Terraform read the token from an environment variable, so it stays out of your code:
Permissions and scopes
A scope is the permission name the API checks, such as vm.write. Each endpoint in the reference says which scope it needs, and the portal’s Read and Edit buttons grant these:
A request without the needed scope is refused before it reaches the product:
The status is 403 Forbidden and required_scope names the missing permission. The portal can’t change an existing token’s permissions: create a new token with the right ones, then revoke the old one.
Tokens made before Virtual Machines was one permission may carry cloud-vm.read, cloud-vm.write, gpu-vm.read or gpu-vm.write. They still work on their own product’s routes; new tokens get vm.*.
Expiry and revoking
To revoke a token, click Revoke on its row, then Revoke token in the Revoke API token dialog. Revoking can’t be undone. The portal can’t extend a token’s expiry: create a new token, switch your programs to it, then revoke the old one.
Security tips
- Never put a token in browser or mobile app code, or commit it to source control. Anyone who has it can use it.
- Give each program its own token with the fewest permissions and workspaces it needs, so you can revoke one without stopping the others.
- Prefer an expiry over No expiration, and replace tokens before they expire.
- If a token may have leaked, revoke it straight away, then check Last Used and your resources for activity you don’t recognise.
Troubleshooting
The error field carries the code. See Errors for the full body and every status.
Related pages
- API overview: your first call, step by step
- API Tokens: the portal page in detail, including S3 credentials
- Rate limits: retrying
429and503 - SDKs, CLI and Terraform
