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:
How it works
- An organization Owner or Admin creates the token and picks its products, workspaces and expiry.
- The portal shows the full token once.
- Your program sends it in the
Authorizationheader, with theworkspace_idof the workspace it is working in. - 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
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.
Name the token
In Name, enter what will use it, for example ci-deploy or nightly-backup-script (up to 100 characters).
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….
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.
Choose when it expires
In Token expiration, pick No expiration (the default), 7 days, 30 days, 90 days or 1 year.
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:
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):
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:
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
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"}.
Related pages
- Authentication: base URLs and how requests are signed
- Object Storage API Credentials: S3 keys for files in buckets
- Team members & access roles: who can create tokens
- Activity logs: see what a token did
