Personal and workspace API keys, who can manage them, and what happens when someone leaves.
Two kinds of key
Every API key belongs to one workspace and has a scope chosen when it is created. The scope decides who the key acts as.
| Personal key | Workspace key | |
|---|---|---|
| Acts as | The person who created it, in that workspace | The workspace itself, not a person |
| Who creates it | Any member | Workspace owners and admins |
| When its creator leaves | Stops working at once, and is revoked | Keeps working |
| Use it for | Your own scripts, local development, tools you run | CI, servers, scheduled jobs, integrations that must outlive any one person |
| API value | scope: "user" | scope: "workspace" |
Keys the platform mints for you are always personal: belt auth token, CLI sign-in on older CLIs, and cloud engines.
Both kinds are pinned to the workspace they were created in and can be narrowed with permission scopes such as apps:execute.
Who sees and manages keys
| Members | Owners and admins | |
|---|---|---|
| Create personal keys | Yes | Yes |
| Create workspace keys | No | Yes |
| List keys | Their own personal keys | Every key in the workspace, with its scope and who created it |
| Revoke keys | Their own personal keys | Any key in the workspace |
A personal workspace has only personal keys.
Manage keys in settings → workspace → api keys, or with the CLI:
1belt keys list2belt keys create laptop # personal3belt keys create ci --workspace --scope apps:execute --ttl 90d4belt keys revoke <id>The full key is shown once, when it is created.
When someone leaves
Removing a member from a workspace, or a member leaving it:
- revokes every personal key they held in that workspace, and their sign-in sessions stop acting there;
- leaves every workspace key they created working. The list still shows them as its creator.
Archiving a workspace ends all of its keys.
Before you remove someone, check settings → workspace → api keys for personal keys that automation depends on, and replace them with workspace keys.
What a workspace key can do
A workspace key acts as a member of its workspace, limited further by its permission scopes. It runs apps, agents and flows, reads and writes the workspace's resources, and is billed and governed like a member: runs go through the workspace's usage policy and are paid for by the workspace (or its organization).
It cannot do what only a person does:
- manage members, billing, the vault, or other admin settings;
- create, list or revoke API keys;
- create workspaces or organizations;
- sign in, approve a device or an OAuth app, or change account settings (the
userandapikeyspermission scopes never apply to it).
Such requests return 403: insufficient_scope for routes behind the user and apikeys scopes, team_role_required for admin settings, person_required for sign-in and approval routes.
Work created with a workspace key is attributed to the workspace's service account rather than a person. The platform records which key made each request.
Keys created before workspace keys
Every key created before workspace keys existed is a personal key of the person who created it. Members see only their own; owners and admins see all of them. To keep an integration working after its creator leaves, create a workspace key for it and revoke the old one.
Next
- API Keys API: create, list and revoke keys over REST, permission scopes
- Authentication: sending a key with a request
- Workspaces: roles and members