Authentication
Create an API key, pick its scope and send it as a bearer token.
The v1 API at https://api.a-line.cloud/v1 only accepts API keys. A
signed-in dashboard session sent to /v1 is refused with
credential_not_accepted.
Create a key
- Open Settings → API Keys in the dashboard.
- Click Create API Key.
- Enter a Name (for example
CI/CD Pipeline) and pick a Scope. - Click Create Key and copy the key, then click Done.
The key is shown once only. Store it somewhere safe, such as your CI's secret store; if you lose it, create a new key.
A key looks like alc_ followed by 48 characters. Only a hash of it is
stored; the list shows the first 12 characters so you can tell keys apart.
A key belongs to the user who created it and to the organization that was active at the time. It acts with that user's access in that organization. You can revoke your own keys from the same page.
API keys cannot create or revoke API keys. Use a signed-in session for that.
Expiry and lockout
- Keys created in the dashboard have no expiry date. They work until you revoke them.
- A key that does carry an expiry date stops working once that moment
passes. It is refused like an unknown key (
401 unauthenticated) and stays in the list until you revoke it. - There is no lockout for API keys. Failed attempts with a wrong key are refused one by one and never block the real key.
- Support can pause a user's keys during an account lock
(
403 api_keys_paused). Paused keys are not revoked.
Scopes
| Scope | Allows |
|---|---|
read | GET, HEAD and OPTIONS requests only. |
write | Every method, including creating, changing and deleting. |
admin | Everything write allows. No v1 operation needs more. |
Reading secret values needs at least write. A request the scope does not
allow is refused with 403 and the code api_key_scope_forbidden.
Send the key
Send the key in the Authorization header. $ALC_API_KEY stands for your key.
GET /v1/clusters
Authorization: Bearer $ALC_API_KEYWhen a key is refused
| Status | Code | Meaning |
|---|---|---|
401 | unauthenticated | No key was sent, or the key is unknown, revoked or expired. |
401 | credential_not_accepted | A session token was sent instead of an API key. |
403 | api_key_scope_forbidden | The key's scope does not allow the request. |
403 | api_keys_disabled | The organization does not allow API keys. |
403 | api_keys_paused | Support locked the owner's account, pausing its keys. |
403 | account_disabled | The key's owner is disabled. |
If an organization turns API keys off, its existing keys stop working too.
See errors for the shape of these responses.