API and MCP

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:

Have a confirmed RepoCloud account — verify your email address
Make a payment of $1 or more — this unlocks API access (go to Billing)

Creating a Key

Dashboard (Recommended)

Go to the API / MCP tab in your dashboard (a signed-out visitor sees an explanation and a sign-in prompt)
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
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.
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.

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 for the full key management reference.

Get started for free