API keys¶
API keys authenticate the althost CLI and other automation against
the control plane. They are an alternative to the portal's session (JWT) login.
The system scopes each key to exactly what the automation needs.
Creating a key¶
Open Settings → API Keys in the portal. Give the key a name. Pick its
scopes. Optionally set an expiry. The full key (ak_…) shows once. Copy
it then. The system stores only a short prefix for display. It stores the key
itself hashed.
Scopes¶
The system restricts a key to the scopes you grant it. It rejects a request
without a required scope with 403.
| Scope | Grants |
|---|---|
read |
Read deploy status (all resource types) |
static-apps:deploy |
Deploy static apps |
services:deploy |
Deploy services |
containers:deploy |
Deploy containers |
databases:deploy |
Deploy databases |
pipelines:read |
List CI/CD pipelines |
pipelines:write |
Report pipeline build results |
auth:users:create |
Create users via the auth API |
auth:users:authenticate |
Authenticate users via the auth API |
auth:users:read |
Read user details via the auth API |
auth:users:delete |
Delete user accounts via the auth API |
Using a key¶
Send the key as a bearer token or an X-Api-Key header:
curl -H "Authorization: Bearer ak_xxx" https://api.althost.dev/v1/deploy/status
The CLI does this for you once you run althost config --api-key ak_xxx.
Revoking¶
Revoke on the key deletes it. Anything using it stops working immediately. A key with an expiry stops working automatically once past it.