# API keys

Keys are hashed at rest; the raw key is returned exactly once, at creation. Name keys at mint time so the list stays legible.

## List keys

```text
GET /v1/api-keys
```

```json
{
  "items": [
    {
      "id": "key_...",
      "name": "production agent",
      "environment": "live",
      "display": "rg_live_...a1b2",
      "last_used_at": "2026-09-02T09:30:00+00:00",
      "revoked": false,
      "created_at": "2026-09-01T12:00:00+00:00"
    }
  ]
}
```

`display` is prefix and suffix only: the full key is never readable after creation.

## Create a key

```text
POST /v1/api-keys
```

```json
{"name": "production agent", "environment": "live"}
```

`environment` is `test` or `live`. Production only mints live keys (test keys belong to the sandbox). The response carries the raw key once:

```json
{"id": "key_...", "api_key": "rg_live_...", "note": "Store this key now — it is shown only once."}
```

## Revoke a key

```text
DELETE /v1/api-keys/{key_id}
```

Revocation is immediate and permanent; mint a new key first when rotating. Rotation is: create the new key, move the integration, revoke the old one.