# Authentication

> Bearer tokens, scopes, and how API keys secure your workspace.

All API requests are authenticated using **bearer tokens** in the standard `Authorization` header. Tokens use the `ax_` prefix and are cryptographically signed, so forged or malformed tokens are rejected before they reach the database.

```
Authorization: Bearer ax_...
```

Tokens are bearer instruments: anyone with the token string can use it. Store them the way you would store a password. Only a salted digest is stored server-side, so even a database breach does not reveal usable tokens.

***

## 🔐 Scopes

Tokens carry one of two scope levels, determined at creation time:

| Scope         | Description                                                                                       |
| :------------ | :------------------------------------------------------------------------------------------------ |
| **Server**    | Global access across all workspaces. Used for administrative operations and workspace management. |
| **Workspace** | Scoped to a single workspace. Can access the documents, jobs and keys of that workspace only.     |

A workspace-scoped token is bound to its workspace at creation and cannot be moved or escalated. Server-scoped tokens are typically reserved for platform administration and are not issued through the standard key creation flow.

### Selecting the Workspace

Paths never name the workspace: a workspace-scoped token always acts on its own. A server-scoped token belongs to no workspace, so it names one in the `X-Workspace-Id` header on every workspace route (`/documents`, `/parsings`, `/keys`, ...):

```
X-Workspace-Id: 018f8e024b2a7c3d9e1f0a2b3c4d5e6f
```

Without the header a server-scoped token gets `400`. A workspace-scoped token may omit it; if it sends another workspace, it gets `403`. Administrative routes under `/admin` ignore the header.

## 🛠️ Key Management

API keys are managed at the workspace level. For a detailed technical reference of every field and parameter, see the [**API Keys reference**](https://docs.axelered.com/reference#auth).

### [Create an API Key](https://docs.axelered.com/reference/auth/api_create_keys_post)

Issue a new bearer token for a workspace. You can optionally set a name and an expiration date.

```bash
curl -X POST "https://api.axelered.com/v1/keys" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Key",
    "expires_in": "90d"
  }'
```

The response includes the full token string in the `secret` field. This is the only time the token is returned in full: store it securely. The token cannot be retrieved again.

### List, Read & Revoke

To manage existing keys, use the following endpoints:

* [**List API Keys**](https://docs.axelered.com/reference/auth/api_list_keys_get): Retrieve all active keys within a workspace.
* [**Delete API Key**](https://docs.axelered.com/reference/auth/api_delete_keys__key_id__delete): Immediately revoke a key. It stops working the moment deletion completes.