Skip to navigation

API Tokens

A platform API token is a secret string that lets a program — a script, the IBEE CLI, an SDK or Terraform — manage your IBEE resources through the IBEE API at https://api.ibee.ai/v1. It works like a password for automation: anyone who has the token can do what its permissions allow, until it expires or you revoke it.

Tokens belong to the organization. You choose which products each token can use, which workspaces it can reach, and when it expires.

Choose the right credential

The API Tokens page in the portal holds four kinds of credential. Pick the one that matches the job:

You want to…UseWhere
Create, list, change or delete VMs, volumes, buckets, networks, load balancers or secrets from codePlatform API token (this page)API Tokens tab
Upload and download files in buckets with the AWS CLI, rclone or an S3 SDKS3 credentialS3 Credentials tab. See Object Storage API Credentials
Push and pull container images with DockerRegistry access tokenRegistry access tokens tab. See Container Registry
Send email from your applicationEmail token or Email Service API keyEmail Tokens tab (shown only when Email Service is enabled). See Email Service
Log in to a Linux VMSSH keySee SSH Keys

How it works

  1. An organization Owner or Admin creates the token and picks its products, workspaces and expiry.
  2. The portal shows the full token once.
  3. Your program sends it in the Authorization header, with the workspace_id of the workspace it is working in.
  4. On every call, IBEE checks that the token is active and not expired, that it has the permission (scope) for that call, that the workspace is allowed, and that the person who created it still has those rights.

Before you begin

  • Role: you must be the organization’s Owner or an Admin. Technical, Collaborator and Billing members don’t see the API Tokens page. See Team members & access roles.
  • Identity verification: your account must be verified. Until it is, the create button reads Verify Identity. See Verify your identity.
  • An organization in good standing: the page is hidden while the organization is restricted. See Billing and usage.
  • The workspace ID of each workspace your program will call. Every request passes it as workspace_id.

Create a token

1

Open API Tokens

Open your organization (the page that lists its workspaces). In the sidebar, under Organization, click API Tokens. The page opens on the API Tokens tab.

2

Start a new token

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

3

Name the token

In Name, enter what will use it, for example ci-deploy or nightly-backup-script (up to 100 characters).

4

Choose the access policy

Under Access policy, choose Entire Organization (every workspace, including ones created later) or Specific Workspaces. For Specific Workspaces, pick one or more workspaces in Select workspaces….

5

Choose permissions

Under Permissions, turn on Read and, only where needed, Edit for each product the program uses. At least one permission is required. The permissions table shows what each one allows.

6

Choose when it expires

In Token expiration, pick No expiration (the default), 7 days, 30 days, 90 days or 1 year.

7

Create and copy the token

Click Create API Token. The API Token Created dialog shows the Bearer token with the message “Copy this token now. It will not be shown again.” Copy it into a safe place, such as your CI system’s secret settings or Secret Manager, then click Done.

The token is shown once only. IBEE can’t show it again. If you lose it, revoke it and create a new one.

Use the token

Send the token as a Bearer token and pass the workspace ID as a query parameter. This request lists the Cloud VMs in a workspace and needs the Virtual Machines → Read permission:

export IBEE_TOKEN="ibee_prod_key_xxxxxxxxxxxx.xxxxxxxx" # the full token you copied
curl "https://api.ibee.ai/v1/compute/cloud-vms?workspace_id=907479" \
-H "Authorization: Bearer $IBEE_TOKEN"

Production tokens start with ibee_prod_key_. The CLI and SDKs read the token from the IBEE_TOKEN environment variable. See Authentication.

Verify it worked

A working token returns 200 OK with a JSON body, and the token’s Last Used time on the API Tokens tab updates. Any other answer has an error code that tells you what is wrong. See Troubleshooting.

Permissions and scopes

Each product row in the dialog grants one or more scopes (named permissions the API checks):

Product rowRead grantsEdit grantsCovers
Virtual Machinesvm.readvm.writeCloud and GPU virtual machines
Object Storageobject-storage.readobject-storage.write, object-storage.deleteBuckets (files use S3 credentials)
Block Storageblock-storage.readblock-storage.writeVolumes, attachments and resizing
CDNcdn.readcdn.writeCDN distributions, cache purge, websites and custom domains
Networkingnetwork.readnetwork.writeVPCs (private networks), subnets, NAT gateways (outbound internet for private servers) and reserved IPs
Firewallfirewall.readfirewall.writeFirewall groups and rules
Load Balancerload-balancer.readload-balancer.writeLoad balancers
Secret Managersecret-store.readsecret-store.writeSecret stores, secrets and access identities
Container Registrycontainer-registry.readcontainer-registry.writeRegistries, repositories and images. Shown only when Container Registry is enabled for your organization
Billingbilling.readbilling.topupThe organisation’s wallet balance. billing.topup creates a Stripe or Razorpay payment page to add credits; nothing is charged until someone pays there. Both also need the billing permission on the organisation (view for the balance, manage for a payment page).

Platform tokens can’t send email, manage team members, read activity logs, open support requests, or manage saved SSH keys or ISOs.

A token never has more rights than the person who created it. If that person leaves the organization or loses access, the token’s calls fail with principal_not_member or principal_permission_denied, even though the token still shows Active.

Manage and revoke tokens

The API Tokens tab lists the organization’s platform tokens:

ColumnShows
NameThe token’s name and the start of its key ID (never the secret)
AccessEntire Organization, or the workspaces it can use
PermissionsThe products it can use
CreatedWhen it was created
Last UsedThe last time a call with it was allowed
StatusActive or Revoked
ActionsRevoke for an active token

The list has no expiry column, and an expired token still shows Active. Note the expiry when you create a token.

To revoke a token: click Revoke. In Revoke API token, click Revoke token. The token stops working immediately and can’t be restored; the row stays in the list as Revoked.

To rotate a token (replace it without downtime): create a new token with the same settings, update your program to use it, check that its Last Used time updates, then revoke the old one.

Limits and timing

Value
Token shownOnce, when it is created
Name1–100 characters
Expiry optionsNo expiration (default), 7 days, 30 days, 90 days, 1 year (365 days)
Workspaces per tokenAll workspaces, or the ones you pick
RevokingTakes effect on the next call: there is no delay
Tokens listed on the pageThe 20 most recently created
Who can create, see and revokeOrganization Owner and Admins

Security tips

  • Give each program its own token, so you can revoke one without breaking the others.
  • Grant Read only, unless the program changes things. Use Specific Workspaces for a program that works in one environment.
  • Pick an expiry for tokens used by people or short projects. Use No expiration only for long-running automation you monitor.
  • Keep tokens out of source code, browser or mobile apps, and logs. Store them in your CI system’s secret settings or in Secret Manager.
  • If a token leaks, revoke it at once, then check Activity logs for calls you don’t recognize.

Troubleshooting

API errors come back as JSON with an error code, for example {"error": "insufficient_scope", "required_scope": "vm.write"}.

You seeWhat it meansWhat to do
The create button reads Verify IdentityYour account isn’t verified yetComplete identity verification
Create API Token stays disabledNo permission is selected, or Specific Workspaces has no workspaceTurn on at least one Read or Edit, and pick a workspace
No API Tokens in the sidebarYou are inside a workspace, you aren’t an Owner or Admin, or the organization is restrictedOpen the organization’s workspace list first. Otherwise ask an Admin
401 invalid_api_keyThe token is missing, mistyped or unknownSend the full token after Bearer , with no extra spaces
400 workspace_id_requiredThe request has no workspace_idAdd ?workspace_id=… to the URL
403 insufficient_scopeThe token lacks the permission named in required_scopeCreate a token with that product’s Read or Edit turned on
403 workspace_not_allowedThe workspace isn’t in the token’s access policy, or isn’t in your organizationUse an allowed workspace, or create a token for this one
403 key_expiredThe token passed its expiryCreate a new token
403 key_revokedThe token was revokedCreate a new token
403 principal_not_member or principal_permission_deniedThe token’s creator left the organization or lost the rights it needsHave a current Admin create a new token
403 verification_required on a changeThe token’s creator isn’t identity-verifiedThe creator completes verification
403 product_not_enabledThe product isn’t enabled for your organizationContact support to request access
403 organization_restricted or 423 organization_suspended on a changeThe organization is restricted or suspendedSee Billing and usage
402 billing_deniedBilling refused a create; billing_reason says whySee Billing admission checks
You lost the tokenIt can’t be shown againRevoke it and create a new one