API Keys & Authentication

The Runnit REST API and MCP server authenticate with per-user API keys. A key belongs to one user in one organisation and acts with that user’s access. There is no service-account mode: every request made with a key is attributed to the person who owns it.

Create a key

1. Sign in to Runnit.
2. Open Admin → API Keys.
3. Enter a Name that describes the integration, for example “CI integration”.
4. Choose Expires in: 30 days, 90 days, 1 year, or 2 years. Two years is the maximum lifetime and the server enforces it.
5. Select Create API key.

The full key starts with rnk_ and is shown once, immediately after creation. Copy it straight into a secret manager. After you dismiss the confirmation, Runnit only ever shows a hint (the first 8 and last 4 characters) so you can recognise the key later.

Caution

Treat the key like a password. Anyone who has it can act as you in your organisation until it expires or you revoke it. If a key is ever exposed, revoke it immediately from Admin → API Keys.

A key is bound to the organisation that was active when you created it. Organisation-scoped requests for any other organisation are rejected, even if you are a member of it. If you work across organisations, create a separate key in each one.

Keys inherit your permissions live

Nothing is baked into a key. On every request, Runnit resolves the owning user’s current role, capabilities, client assignments, and data-access restrictions, exactly as it does for a browser session. That means:

• if your permissions change, every existing key follows immediately;
• a key can never do more than you can do in the app; and
• if your account is deactivated or you lose access to the organisation, the key stops working straight away.

Send the key with requests

There are three ways to present a key, in order of preference:

1. Authorization header (recommended)

   curl https://api.runnit.io/api/v1/projects \
     -H 'Authorization: Bearer rnk_your_key'

2. x-runnit-api-key header

   curl https://api.runnit.io/api/v1/projects \
     -H 'x-runnit-api-key: rnk_your_key'

3. apiKey field in the JSON request body, on POST, PATCH, and PUT requests only:

   { "apiKey": "rnk_your_key", "name": "Draft homepage copy" }

The body option exists for tools that cannot set request headers. Prefer a header when you can: request bodies are more likely to be logged by intermediaries, and GET and DELETE requests have no body to carry the key. Runnit removes the apiKey field from the body before your request is processed.

The same key also authenticates the MCP server, either as an Authorization: Bearer rnk_... header or as the per-tool apiKey argument. See MCP Server.

Expiry and revocation

• Keys live for at most 2 years; shorter expiries are safer for keys you can rotate easily.
• Revoke your own keys at any time from Admin → API Keys using Revoke, then Confirm revoke.
• Organisation admins and owners see every member’s keys in the Organisation API keys list on the same page and can revoke any of them.
• A revoked or expired key fails immediately; there is no grace period.
• The Last used column shows when each key last authenticated a request, which helps you spot unused or unexpected keys.

Rate limits

Each key can make up to 600 requests per minute by default (deployments can configure a different limit). Requests over the limit return 429. Spread bulk work out or batch it rather than retrying immediately.

Errors

Status	Meaning
401	The key is missing, invalid, expired, or revoked, or the owning user is deactivated or no longer a member of the organisation.
403	The key is valid but the request targets a different organisation than the key is bound to, or the owning user lacks permission for the action.
429	The key exceeded its per-minute rate limit. Wait and retry.

Next step

Explore the endpoints in the REST API Overview, or connect an AI agent through the MCP server.