Skip to navigation

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:

You want to…UseTab
Call the IBEE API, SDKs, CLI or TerraformAPI token (this page)API Tokens
Read and write files in buckets with S3 tools (AWS CLI, boto3, rclone)S3 credentialS3 Credentials
docker login, push and pull imagesRegistry access tokenRegistry access tokens
Send email through Email ServiceEmail tokenEmail Tokens (shown when Email Service is enabled)

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

  1. You create the token in the portal and choose its permissions (which products, read or edit), its access policy (which workspaces) and its expiration.
  2. Your program sends Authorization: Bearer <token> with every request.
  3. 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

1

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.

2

Start a new token

Click Create API Token. The Create API Token dialog opens.

3

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.

4

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.
5

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.

6

Choose an expiration

Under Token expiration, pick No expiration (the default), 7 days, 30 days, 90 days or 1 year. For automation, an expiry of 90 days or less limits the damage if the token leaks.

7

Create it and copy the token

Click Create API Token. The API Token Created dialog shows the Bearer token with a copy button and the warning “Copy this token now. It will not be shown again.” Store it in a password manager or your CI system’s secret store before you close the dialog.

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:

export IBEE_TOKEN="ibee_prod_key_xxxxxxxxxxxx"
export IBEE_WORKSPACE_ID="907479"
curl "https://api.ibee.ai/v1/compute/sites?workspace_id=$IBEE_WORKSPACE_ID" \
-H "Authorization: Bearer $IBEE_TOKEN"

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:

ToolTokenWorkspace
Python and TypeScript SDKsIBEE_API_TOKEN, then IBEE_TOKENIBEE_WORKSPACE_ID
CLIIBEE_TOKEN, then IBEE_API_TOKEN (or --token)IBEE_WORKSPACE_ID (or --workspace)
Terraform providerIBEE_TOKEN (or the provider’s token)IBEE_WORKSPACE_ID (or workspace_id)

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:

Portal permissionRead grantsEdit also grantsCovers
Virtual Machinesvm.readvm.writeCloud and GPU VMs, their snapshots and backups, the compute catalog (sites, plans, images) and VM operations
Object Storageobject-storage.readobject-storage.write, object-storage.deleteBuckets, bucket settings and S3 credentials. Every DELETE needs object-storage.delete, except deleting an S3 credential, which needs object-storage.write, as revoking one does.
Block Storageblock-storage.readblock-storage.writeVolumes, resizing and volume operations
CDNcdn.readcdn.writeDistributions, website settings, custom domains, metrics and cache purges
Networkingnetwork.readnetwork.writeVPCs, subnets, VM attachments, NAT gateways (which let private VMs reach the internet through a shared public IP), port forwarding and Reserved IPs
Firewallfirewall.readfirewall.writeFirewall groups, rules and VM attachments
Load Balancerload-balancer.readload-balancer.writeLoad balancers and their status
Secret Managersecret-store.readsecret-store.writeStores, secrets, versions, identities and scopes. Reading an identity’s login details needs secret-store.write, because each read issues a new secret ID.
Container Registrycontainer-registry.readcontainer-registry.writeRegistries, storage plans, registry access tokens, repositories, images, scans, SBOMs (software bills of materials: lists of what an image contains) and metrics. Shown only when Container Registry is enabled for your organization.
Billingbilling.readbilling.topupbilling.read: the organisation’s wallet balance (GET /v1/billing/wallet), with the person’s view-billing permission. billing.topup: a hosted Stripe or Razorpay payment page to add credits (POST /v1/billing/topups), with the manage-billing permission; it charges nothing by itself.

A request without the needed scope is refused before it reaches the product:

{
"error": "insufficient_scope",
"required_scope": "vm.write",
"billing_reason": null,
"billing_sku_code": null,
"billing_evaluated_at": null,
"admission_context_id": null
}

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

EventWhat happensError your program gets
The token reaches its expiry dateEvery request is refused403 key_expired
You click RevokeThe token stops working at once; its status becomes Revoked403 key_revoked
The person who created the token leaves the organization or loses accessRequests are refused403 principal_not_member, principal_inactive or principal_permission_denied

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

You seeWhat it meansWhat to do
401 invalid_api_keyThe header is missing, the token is cut short, or it belongs to the other environmentSend Authorization: Bearer <token> with the whole token, and use the base URL that matches its prefix.
403 insufficient_scopeThe token lacks the permission in required_scopeCreate a token with that permission.
403 workspace_not_allowedThe token is limited to other workspaces, or the workspace ID is wrong or deletedCheck workspace_id, or create a token for this workspace.
403 key_expiredThe token passed its expiry dateCreate a new token.
403 key_revoked, key_disabled or key_inactiveThe token was revoked or is not activeCreate a new token.
403 principal_not_member, principal_inactive or principal_permission_deniedThe token’s creator no longer has access to this organization or workspaceHave a current owner or administrator create a new token.
403 verification_required on a writeThe token’s user hasn’t finished identity verificationComplete verification in the portal.
403 organization_restricted on a writeAn IBEE administrator restricted the organizationContact support.
423 organization_suspended on a writeThe organization is suspendedContact support.
403 product_not_enabledThe product is not turned on for your organizationAsk support for access.
The button says Verify IdentityIdentity verification isn’t completeFinish verification first.
”Organization API tokens unavailable”You aren’t an owner or administratorAsk one to create the token.

The error field carries the code. See Errors for the full body and every status.