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

# API keys

> Create, list, and revoke API keys.

API keys are per workspace. The full key is shown **once** at creation.

## Endpoints

| Method   | Path            | Purpose                                                                           |
| -------- | --------------- | --------------------------------------------------------------------------------- |
| `GET`    | `/api-keys`     | List keys (prefix only, never full key)                                           |
| `POST`   | `/api-keys`     | Create a key (returns full key once) — pass `read_only: true` for a read-only key |
| `DELETE` | `/api-keys/:id` | Soft-revoke a key                                                                 |

See [Authentication](/docs/concepts/authentication) for storage details.

## `POST /api-keys`

```bash theme={null}
curl -X POST $SALTY_API/api-keys \
  -H "Authorization: Bearer $SALTY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"agent-1"}'
```

```json theme={null}
{
  "id": "08e7e7d4-31ff-4456-bd99-731252edb54c",
  "prefix": "sk_live_2AnWRAES",
  "name": "agent-1",
  "scopes": ["*"],
  "key": "sk_live_2AnWRAESct7R7zJuiBU6",
  "last_used_at": null,
  "created_at": "2026-05-24T02:00:00Z",
  "revoked_at": null
}
```

<Warning>
  The `key` field is included only in this response. Store it; you can't fetch it again.
</Warning>

### Read-only key

Pass `read_only: true` to mint a key scoped to reads only:

```bash theme={null}
curl -X POST $SALTY_API/api-keys \
  -H "Authorization: Bearer $SALTY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"reporting-agent","read_only":true}'
```

The response is the same shape, but with `"scopes": ["read"]`. A read-only key can call `GET` endpoints but any write (POST/PATCH/DELETE) returns `403 insufficient_scope`.

## `GET /api-keys`

```json theme={null}
{
  "data": [
    {
      "id": "08e7e7d4-31ff-4456-bd99-731252edb54c",
      "prefix": "sk_live_2AnWRAES",
      "name": "agent-1",
      "scopes": ["*"],
      "last_used_at": "2026-05-24T03:14:00Z",
      "created_at": "2026-05-24T02:00:00Z",
      "revoked_at": null
    }
  ]
}
```

## `DELETE /api-keys/:id`

```bash theme={null}
curl -X DELETE $SALTY_API/api-keys/08e7e7d4-... \
  -H "Authorization: Bearer $SALTY_API_KEY"
```

Returns `204`. The revoked key immediately fails auth on subsequent requests with `401 invalid_api_key`. Calling DELETE on an already-revoked key returns `404`.