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

# API Key Management

> Create, list, and revoke API keys for programmatic access

## Overview

API keys are managed through the `/api/v1/keys` endpoints. Unlike the instance endpoints, key management uses **session authentication** (your browser login) rather than Bearer token authentication, and the session is tied to the browser that opened it. This means these endpoints are primarily used by the dashboard UI.

For most users, the [API / MCP tab](https://repocloud.io/mcp) in the dashboard (its page is called "AI Agent Portal") is the simplest way to manage keys. The calls below are kept as a reference.

> [!NOTE]
>
> Key management endpoints require a signed-in browser session (cookie-based auth). Listing needs nothing more; creating and revoking also need a CSRF token, sent as the `X-CSRFToken` header. They cannot be called with a Bearer API key: a call that is not signed in, or that carries only a Bearer header, is redirected (302) to the login page. A session works only from the browser that opened it: a pasted cookie is accepted only from a client that also sends the browser's exact `User-Agent` (and it may need the same address), and a mismatch signs the browser out.

---

## List Keys

Retrieve all API keys for your account, newest first. Revoked keys are listed too, with `is_active` set to `false`.

```
GET /api/v1/keys
```

### Example Request

```bash
curl https://repocloud.io/api/v1/keys \
  -H "Cookie: session=your_session_cookie" \
  -H "User-Agent: your_browsers_user_agent"
```

### Response (200 OK)

```json
[
  {
    "id": 1,
    "name": "Default",
    "key_prefix": "rcmcp_a1b2c3",
    "is_active": true,
    "created_at": "2026-07-15T10:00:00",
    "last_used_at": "2026-07-20T14:30:00"
  },
  {
    "id": 2,
    "name": "CI Pipeline",
    "key_prefix": "rcmcp_d4e5f6",
    "is_active": true,
    "created_at": "2026-07-18T09:00:00",
    "last_used_at": null
  }
]
```

The times are UTC with no zone suffix.

> [!NOTE]
>
> The full key is never returned by the list endpoint. Only the `key_prefix` (first 12 characters) is shown for identification.

---

## Create a Key

Generate a new API key.

```
POST /api/v1/keys
```

### Prerequisites

You need a payment of at least $1.00 on your account to create API keys. Without it, the endpoint returns HTTP 402.

### Request Headers

| Header | Required | Description |
|--------|----------|-------------|
| `X-CSRFToken` | Yes | CSRF token of your session: the value of the `csrf-token` meta tag of the API / MCP page, valid for 60 minutes |
| `Cookie` | Yes | Your session cookie |
| `User-Agent` | From a script | The exact `User-Agent` of the browser that holds the session |

### Request Body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `name` | string | No | A label for the key (max 100 characters, defaults to "Default") |

### Example Request

```bash
curl -X POST https://repocloud.io/api/v1/keys \
  -H "Content-Type: application/json" \
  -H "X-CSRFToken: your_csrf_token" \
  -H "Cookie: session=your_session_cookie" \
  -H "User-Agent: your_browsers_user_agent" \
  -d '{"name": "Production Deploy"}'
```

### Response (201 Created)

```json
{
  "id": 3,
  "name": "Production Deploy",
  "key_prefix": "rcmcp_012345",
  "full_key": "rcmcp_0123456789abcdef0123456789abcdef",
  "created_at": "2026-07-25T12:00:00"
}
```

> [!WARNING]
>
> The `full_key` is only returned in this response; the dashboard shows a key once as well. Copy and store it securely. It cannot be retrieved again — you will only see the `key_prefix` in future requests.

### Error Responses

| Status | Error | Cause |
|--------|-------|-------|
| 302 | Redirect to `/login` | The call is not signed in, or carries only a Bearer header |
| 402 | `Deposit required` | You need a payment of at least $1.00 on your account before creating keys; the answer's `detail` reads "Make a deposit of $1 or more to unlock API access." |
| 403 | `CSRF validation failed` | Missing or invalid `X-CSRFToken` header. This check comes before the payment check, and the token is valid for 60 minutes |

---

## Revoke a Key

Permanently deactivate an API key. Revoked keys cannot be used for API requests.

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

### Path Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `key_id` | integer | The key ID to revoke |

### Request Headers

| Header | Required | Description |
|--------|----------|-------------|
| `X-CSRFToken` | Yes | CSRF token of your session: the value of the `csrf-token` meta tag of the API / MCP page, valid for 60 minutes |
| `Cookie` | Yes | Your session cookie |
| `User-Agent` | From a script | The exact `User-Agent` of the browser that holds the session |

### Example Request

```bash
curl -X DELETE https://repocloud.io/api/v1/keys/2 \
  -H "X-CSRFToken: your_csrf_token" \
  -H "Cookie: session=your_session_cookie" \
  -H "User-Agent: your_browsers_user_agent"
```

### Response (200 OK)

```json
{
  "ok": true,
  "id": 2
}
```

A second revoke of the same key answers the same 200, and the key stays in the list with `is_active` set to `false`.

### Error Responses

| Status | Error | Cause |
|--------|-------|-------|
| 302 | Redirect to `/login` | The call is not signed in, or carries only a Bearer header |
| 403 | `CSRF validation failed` | Missing or invalid `X-CSRFToken` header; the token is valid for 60 minutes |
| 404 | `Key not found` | Key does not exist or belongs to another user |

> [!NOTE]
>
> Revocation is immediate. A revoked key is refused on every new request, with a 401 `Invalid or revoked API key`; a request that was already accepted finishes. Servers made with the key stay, and any other key of the account manages them.