API keys and automation
Driving the platform from a script, and the two rules that make a key safe to leave on a build server.
You can mint keys that call the platform API as you, for CI jobs and scripts. Profile → API keys.
A key is you, narrowed
A key authenticates as its owner and can only ever do a subset of what that person could do in the console. It carries no role of its own. Your project roles still apply, after the key’s own scope check.
It never widens anything. Two consequences worth knowing:
Administrator routes are unreachable with an API key, even when the owner is a platform administrator. That is not an oversight — it means a leaked key is a problem confined to one tenant rather than to the platform. Automation that genuinely needs administrator powers uses a service token instead, which is a separate thing an operator issues deliberately.
A key fails closed. It reaches only the operations its scopes name. Anything not on that list is refused before the handler runs, so a route added tomorrow is not silently reachable by a key minted today.
Scopes
Read and write per noun, matching the console’s own vocabulary:
| Scope | |
|---|---|
workspaces:read / workspaces:admin |
projects, members, bindings, quotas, network policy |
workloads:read / workloads:write |
deployments, pods, events, metrics, logs; create, stop, resume, restart, delete |
endpoints:read / endpoints:write |
public HTTP endpoints, and minting access tokens for them |
storage:read / storage:write |
objects, usage, presigned URLs, multipart, rename, delete |
inference:read / inference:write |
the model catalog, and minting inference keys |
billing:read |
wallet, usage, invoices, auto-recharge status |
There is deliberately no billing:write. A key can see what you have
spent. It cannot spend.
Narrowing to one project
A key may be pinned to a single project. When it is, any request naming a different one is refused before the handler runs, and list endpoints return only that project.
Pin your CI key. A build job for one service has no reason to be able to read — or stop — everything else you own.
Handling the secret
The key looks like alx_api_… and is shown once, at creation. Only a hash
is stored, so a lost key cannot be recovered, only replaced. The console keeps
the first few characters so you can tell keys apart in a list.
Give each key a name and an expiry. Keys record when they were last used, which is how you find the one nobody needs any more.
The audit trail names the key
Actions taken with a key are recorded against that key, not merely against you. When something unexpected happens, the log says which credential did it — which is the difference between revoking one build server’s access and changing your password.
Revoking is immediate.