> ## 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.

# Authentication

> Create API keys, authenticate requests with Bearer tokens, and understand rate limits

## API Keys

Every call to the server endpoints (instances and their actions) is authenticated with a Bearer token in the `Authorization` header. API keys are prefixed with `rcmcp_` and are tied to your RepoCloud account. A key is `rcmcp_` plus 32 hexadecimal characters, 38 in all; the dashboard shows `rcmcp_` plus 6 characters and four dots.

The key routes (create, list, and revoke) and the API / MCP page use your dashboard session instead, a cookie plus a CSRF value: a Bearer-only call to them is redirected to the login page. The OpenAPI file at `https://repocloud.io/api/v1/openapi.json` needs no key.

### Prerequisites

Before you can create an API key, you must:

1. **Have a confirmed RepoCloud account** — verify your email address
2. **Make a payment of $1 or more** — this unlocks API access (go to [Billing](https://repocloud.io/billing))

### Creating a Key

**Dashboard (Recommended)**

1. Go to the [API / MCP tab](https://repocloud.io/mcp) in your dashboard (a signed-out visitor sees an explanation and a sign-in prompt)
2. The first time you open the page with a payment of $1 or more and no active key, RepoCloud creates a key named **Default** and shows it once. The same happens after you revoke your last active key. Without the payment, no key is made
3. **Copy the full key immediately** — it is only shown once. You can see the prefix (`rcmcp_xxxxxx...`) later, but the full key cannot be retrieved.
4. To create additional keys, click **Generate New Key**. A key made on the page is always named **Default**, and without a payment of $1 the button opens a "Deposit Required" notice instead of creating a key

**API**

The key routes belong to the dashboard page. A call needs your signed-in browser session (session auth, not Bearer auth) and a CSRF value from the `csrf-token` meta tag of the API / MCP page, valid for 60 minutes. 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); a mismatch signs the browser out.

```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": "My CI Key"}'
```

The CSRF value, the cookie, and the `User-Agent` are placeholders. The answer is HTTP 201 with five fields: `id`, `name`, `key_prefix`, `full_key`, and `created_at`. The `full_key` field holds the whole key, and this is the only time it is returned.

> [!WARNING]
>
> Store your API key securely. The full key is only shown at creation time. If you lose it, revoke the key and create a new one.

## Using Your Key

Include the API key in the `Authorization` header of every call to the server endpoints:

```bash
curl https://repocloud.io/api/v1/instances \
  -H "Authorization: Bearer rcmcp_your_full_key_here"
```

### Authentication Errors

| Status | Error | Meaning |
|--------|-------|---------|
| 401 | `Missing or malformed Authorization header` | No `Authorization: Bearer ...` header found. The word `Bearer` is case-sensitive: a lower-case `bearer` or a bare key gives this error, with the hint `Use: Authorization: Bearer rcmcp_...` |
| 401 | `Invalid API key prefix` | Key does not start with `rcmcp_` |
| 401 | `Invalid or revoked API key` | Key not found or has been revoked |
| 401 | `API key owner not found` | Account associated with key no longer exists |
| 403 | `Account suspended` | Your account has been suspended |
| 403 | `Account not confirmed` | Email address not yet verified |

## Rate Limits

The API enforces two rate limits per API key, over rolling windows:

| Scope | Limit | Window |
|-------|-------|--------|
| **General** (every call made with an API key) | 60 requests | 60 seconds |
| **Deploy** (`POST /api/v1/instances`) | 5 requests | 1 hour |

Every `POST` to the deploy path counts toward the five, including a call refused for bad input. When you exceed a rate limit, the API returns:

```json
HTTP/1.1 429 Too Many Requests
Retry-After: 42

{
  "error": "Rate limit exceeded",
  "retry_after": 42
}
```

The `Retry-After` header and the `retry_after` field carry the same whole number of seconds to wait before retrying. The 42 is an example: the number is the seconds until the oldest counted call leaves the window, at most 60 for the general limit and at most 3600 for deploys.

### Rate Limit Strategy

- Rate limits are tracked **per API key**, not per account. The counters live in the memory of each web server process, so the real ceiling can be higher than the figures
- Each key has its own counters, so a second key has its own limits
- The deploy limit (5 per hour) applies only to `POST /api/v1/instances` — listing, getting details, actions, and deletions count against the general limit only

## Payment Gate

API key creation requires a payment of $1 or more, once: after such a payment at any point, API access remains unlocked even if your balance later drops below $1, and a key that already exists keeps working whatever the balance.

Deploying instances through the API additionally requires a balance greater than $3 at the time of the deploy request. This is the same requirement as deploying through the web dashboard.

## Key Revocation

Revoke a key from the dashboard or via the API. Revoked keys are immediately deactivated and cannot be reused. The dashboard asks for confirmation and no longer lists a revoked key; the API list still returns it, with `is_active` set to false. The API call is a session call with a CSRF value, like creating a key:

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

The 42 is an example id. The answer is `{"ok": true, "id": 42}`; a missing key or another account's key answers 404 `Key not found`.

See [API Key Management](https://repocloud.io/docs/api/keys.md) for the full key management reference.