> ## Documentation Index
> Fetch the complete documentation index at: https://docs.repocloud.io/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

All API requests are authenticated with Bearer tokens. API keys are prefixed with `rcmcp_` and are tied to your RepoCloud account.

### Prerequisites

Before you can create an API key, you must:

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

### Creating a Key

<Tabs>
  <Tab title="Dashboard (Recommended)">
    1. Go to the [API / MCP tab](https://repocloud.io/mcp) in your dashboard
    2. If this is your first visit and you have deposited \$1 or more, a **Default** key is automatically created and displayed
    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 **Create New Key** and provide a name
  </Tab>

  <Tab title="API">
    Create a key programmatically (requires an active browser session — this endpoint uses session auth, not Bearer auth):

    ```bash theme={null}
    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" \
      -d '{"name": "My CI Key"}'
    ```

    The response includes the full key in the `full_key` field — this is the only time it is returned.
  </Tab>
</Tabs>

<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.
</Warning>

## Using Your Key

Include the API key in the `Authorization` header of every request:

```bash theme={null}
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  |
| 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 banned                 |
| 403    | `Account not confirmed`                     | Email address not yet verified               |

## Rate Limits

The API enforces two rate limit tiers per API key:

| Scope                                 | Limit       | Window     |
| ------------------------------------- | ----------- | ---------- |
| **General** (all endpoints)           | 60 requests | 60 seconds |
| **Deploy** (`POST /api/v1/instances`) | 5 requests  | 1 hour     |

When you exceed a rate limit, the API returns:

```json theme={null}
HTTP/1.1 429 Too Many Requests
Retry-After: 42

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

The `Retry-After` header and `retry_after` field indicate how many seconds to wait before retrying.

### Rate Limit Strategy

* Rate limits are tracked **per API key**, not per account
* Creating multiple keys does not increase your total rate limits — each key has its own independent counters
* 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

## Deposit Gate

API key creation requires a minimum \$1 deposit. This is a one-time requirement — once you have deposited \$1 or more at any point, API access remains unlocked even if your balance later drops below \$1.

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.

```bash theme={null}
curl -X DELETE https://repocloud.io/api/v1/keys/42 \
  -H "X-CSRFToken: your_csrf_token" \
  -H "Cookie: session=your_session_cookie"
```

See [API Key Management](/api/keys) for the full key management reference.