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

# API keys

> Mint, list, and revoke API keys. Admin only.

Requires the `admin` action. See [Authentication](/authentication) for scoping.

***

## List keys

```http theme={null}
GET https://api.userepo.com/v1/api-keys
```

Returns all non-revoked keys for the organization.

```json theme={null}
{
  "apiKeys": [
    {
      "id": "uuid",
      "name": "support-agent-prod",
      "prefix": "repo_a1b2",
      "actorType": "agent",
      "allowedActions": ["search", "context", "ask"],
      "allowedProviders": ["slack", "notion"],
      "lastUsedAt": "2026-05-30T19:42:00Z",
      "createdAt": "2026-05-23T18:33:00Z"
    }
  ]
}
```

Note: the response includes `prefix` (the first 8 chars of the key) but **never the full secret**. The full secret is only available at creation time.

***

## Create a key

```http theme={null}
POST https://api.userepo.com/v1/api-keys
```

<ParamField body="name" type="string" required>Human-facing label. Min 1, max 80 chars.</ParamField>
<ParamField body="actorType" type="string" default="agent">One of `agent`, `application`, `admin`.</ParamField>
<ParamField body="allowedActions" type="string[]" required>Array of actions (see [Authentication → Actions](/authentication#actions)). Min 1 entry.</ParamField>
<ParamField body="allowedProviders" type="string[]" default="null">Whitelist of provider IDs. `null` = no restriction.</ParamField>

### Response

```json theme={null}
{
  "apiKey": {
    "id": "uuid",
    "name": "support-agent-prod",
    "secret": "repo_live_a1b2c3d4e5f6...",
    "prefix": "repo_a1b2",
    "actorType": "agent",
    "allowedActions": ["search", "context", "ask"],
    "allowedProviders": ["slack", "notion"],
    "createdAt": "2026-05-30T20:14:00Z"
  }
}
```

<Warning>
  The `secret` field is returned **only on creation**. Repo stores a SHA-256 hash and cannot recover the secret. If you lose it, revoke the key and create a new one.
</Warning>

### Tier limits

Each plan caps the number of active API keys:

| Tier    | Max keys  |
| ------- | --------- |
| Builder | 2         |
| Studio  | 10        |
| Scale   | Unlimited |

Hitting the cap returns `403 agent_limit_reached`. Upgrade in the console to add more.

***

## Revoke a key

```http theme={null}
DELETE https://api.userepo.com/v1/api-keys/{id}
```

Sets `revoked_at` on the row; future requests using the key get `401 Invalid API key` immediately (no cache).

Repo refuses to revoke the key currently authenticating the request — you can't lock yourself out by accident. Use a different admin key to revoke this one.

```json theme={null}
{ "revoked": true, "id": "uuid" }
```