# API Keys

Canonical HTML: https://anchorshell.com/docs/api-keys

Create, scope, rename, and revoke individually attributable hosted API keys.

Last updated: 2026-09-17

An API key authenticates a workload as its owner. Requests retain the owner's organization, current permissions, and plan entitlements, narrowed by the key's scopes. Revoking a key stops new authentication without changing other keys.

Use one key per application or agent for independent attribution and [budgets](https://anchorshell.com/docs/limits). Self-hosted Relay instead has one deployment-wide `RELAY_API_TOKEN`; its separate `RELAY_ADMIN_TOKEN` manages configuration.

## Dashboard

1. Open **Account → API keys** and name the workload.
2. For inference, leave management access unchecked. For permitted management operations, select **Allow management API access using my current permissions**.
3. Create the key and copy the secret once into your application's secret manager.
4. Use **Edit name** or **Revoke** on an existing key.

Existing keys do not gain scopes automatically. The management option captures your current permissions; later removals take effect immediately, while new grants require a new key. Users with the appropriate security permission can also inspect and revoke organization keys.

## API

Use a key with the relevant permissions; see [API authentication](https://anchorshell.com/docs/api). Replace placeholders with IDs from the corresponding list or create response.

Managing your own keys requires `cloud:account:manage`. A key cannot create another key with broader scopes than itself. Team delegation additionally requires a key carrying all of its owner's current permissions.

### List your keys

```bash
curl 'https://api.anchorshell.com/api/account/api-keys' \
  -H 'Authorization: Bearer <API_KEY>'
```

**Response — 200 OK**

Selected response fields shown; IDs and values are illustrative.

```json
{
  "api_keys": [
    {
      "id": "<API_KEY_ID>",
      "user_uuid": "<USER_ID>",
      "name": "support-agent",
      "key_prefix": "<KEY_PREFIX>",
      "product_key": "model_relay",
      "scopes": [
        "relay:request"
      ],
      "status": "active",
      "last_used_at": null,
      "expires_at": null,
      "revoked_at": null
    }
  ]
}
```

### List your available scopes

```bash
curl 'https://api.anchorshell.com/api/account/api-key-scopes' \
  -H 'Authorization: Bearer <API_KEY>'
```

**Response — 200 OK**

Example permitted scopes; the list varies with the owner and calling key.

```json
{
  "scopes": [
    "relay:request",
    "relay:providers:read",
    "relay:providers:manage",
    "cloud:account:manage"
  ]
}
```

### Create an inference key

```bash
curl -X POST 'https://api.anchorshell.com/api/account/api-keys' \
  -H 'Authorization: Bearer <API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "support-agent",
  "scopes": [
    "relay:request"
  ]
}'
```

**Response — 201 Created**

The api_key secret is returned only here. Copy it now; key.id is the public ID.

```json
{
  "api_key": "<NEW_API_KEY>",
  "key": {
    "id": "<API_KEY_ID>",
    "user_uuid": "<USER_ID>",
    "name": "support-agent",
    "key_prefix": "<KEY_PREFIX>",
    "product_key": "model_relay",
    "scopes": [
      "relay:request"
    ],
    "status": "active",
    "last_used_at": null,
    "expires_at": null,
    "revoked_at": null
  }
}
```

The response's `api_key` field contains the secret once; `key.id` is its public ID. Save the secret securely. List responses never reveal it.

### Create a narrowly scoped management key

```bash
curl -X POST 'https://api.anchorshell.com/api/account/api-keys' \
  -H 'Authorization: Bearer <API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "provider-automation",
  "scopes": [
    "relay:providers:manage"
  ]
}'
```

**Response — 201 Created**

The api_key secret is returned only here. Copy it now; key.id is the public ID.

```json
{
  "api_key": "<NEW_API_KEY>",
  "key": {
    "id": "<API_KEY_ID>",
    "user_uuid": "<USER_ID>",
    "name": "provider-automation",
    "key_prefix": "<KEY_PREFIX>",
    "product_key": "model_relay",
    "scopes": [
      "relay:providers:read",
      "relay:providers:manage"
    ],
    "status": "active",
    "last_used_at": null,
    "expires_at": null,
    "revoked_at": null
  }
}
```

### Rename a key

```bash
curl -X PATCH 'https://api.anchorshell.com/api/account/api-keys/<API_KEY_ID>' \
  -H 'Authorization: Bearer <API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "support-agent-production"
}'
```

**Response — 204 No Content**

No response body.

### Revoke a key

```bash
curl -X DELETE 'https://api.anchorshell.com/api/account/api-keys/<API_KEY_ID>' \
  -H 'Authorization: Bearer <API_KEY>'
```

**Response — 204 No Content**

No response body.

Key scopes are immutable after creation. Create a replacement when required access changes.

## Next

[Billing](https://anchorshell.com/docs/billing).