> ## Documentation Index
> Fetch the complete documentation index at: https://docs.beta.ontoto.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> How to generate and use API tokens

All API requests must be authenticated using an API token passed in the `x-api-key` header.

```bash theme={null}
curl https://api.beta.ontoto.com/v1/devices \
  -H "x-api-key: <your-token>"
```

## Generating a token

1. In the Ontoto Dashboard sidebar, navigate to **Developer → API Tokens**.
2. Click **Create Token**.
3. Enter a **name** and optional **description** for the token.
4. Set an **expiry date**.
5. Choose an [access scope](#access-scopes).
6. Click **Create Token**.

The token value is displayed once immediately after creation. Copy and store it securely; it cannot be retrieved again.

## Access scopes

Tokens currently grant **read-only** access. Write access may be added in the future for
programmatic device management. When creating a token, you choose one of two access modes:

### All devices, groups, and sites

Grants read access to every device, device group, and site in your organisation.

### Scoped access

Grants read access only to the specific resources you select. You can mix and match across three resource types:

| Resource type    | Description                                  |
| ---------------- | -------------------------------------------- |
| **Device**       | A single device, identified by serial number |
| **Device group** | A named group of devices                     |
| **Site**         | A site that devices are assigned to          |

Permissions cannot be changed after a token is created.

## Managing tokens

| Action         | Description                                                                                |
| -------------- | ------------------------------------------------------------------------------------------ |
| **Regenerate** | Issues a new token value with a new expiry date. The old token is immediately invalidated. |
| **Delete**     | Permanently revokes the token. This cannot be undone.                                      |