> Index of every page on this site: [llms.txt](https://docs.a-line.cloud/llms.txt)

# 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

1. Open **Settings → API Keys** in the dashboard.
2. Click **Create API Key**.
3. Enter a **Name** (for example `CI/CD Pipeline`) and pick a **Scope**.
4. Click **Create Key** and copy the key, then click **Done**.

<Callout type="warn">
  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.
</Callout>

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.

```http api
GET /v1/clusters
Authorization: Bearer $ALC_API_KEY
```

## When 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](/api/errors) for the shape of these responses.
