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

# Authentication

> Create Revilico API keys, send them as bearer tokens, limit access with scopes, rotate or revoke keys, and resolve authentication errors.

Every request to the REST API needs an API key, sent as a bearer token:

```bash theme={null}
curl https://public-api.revilico.bio/v1/me \
  -H "Authorization: Bearer rvl_live_…"
```

A key acts as you. It can only reach what your account can reach in the web app: your runs, the runs and projects shared with you, and the engines your plan includes. Runs it starts use your organization's credits.

> [!NOTE]
>
> AI apps connecting to the [MCP server](https://docs.revilico.bio/developers/mcp/overview.md) don't need an API key: you sign in with your Revilico account instead.

## Create a key

1. In the [Revilico web app](https://app.revilico.bio/account/developer), open your account and click **Developer** in the sidebar.
2. On the **API keys** tab, click **Create API key**.
3. Give the key a name that says where it is used, such as "Screening pipeline".
4. Choose its access: **Full access**, **Read only** or **Custom** (see [Scopes](#scopes)).
5. Choose when it expires: in 30, 90, 180 or 365 days.
6. Copy the key. You won't be able to see it again.

Keys start with `rvl_live_`. You can have up to 10 active keys.

> [!WARNING]
>
> Treat a key like a password. Keep it in an environment variable or a secrets manager, never in code you commit or share. If a key leaks, revoke it.

## Scopes

Scopes limit what a key can do. They never give a key more access than your account has.

| Scope | Allows |
| - | - |
| `engines:read` | Browse engines, their parameter schemas and examples |
| `files:write` | Upload input files |
| `runs:write` | Start and cancel runs; create projects and add or remove runs |
| `runs:read` | View runs, their status and inputs; list projects |
| `data:read` | Read results, list run files and download outputs |
| `account:read` | View your credit balance and usage |

**Full access** has every scope. **Read only** has `engines:read`, `runs:read`, `data:read` and `account:read`, so the key can look at everything but can't start runs or spend credits.

Each endpoint in the [API reference](https://docs.revilico.bio/api-reference/introduction.md) lists the scope it needs. A key without it gets `403 INSUFFICIENT_SCOPE`. `GET /v1/me` works with any scope and shows the key's scopes.

## Rotate a key

Rotating replaces a key with a new one that has the same name, scopes and lifetime. On the **API keys** tab, click **Rotate** next to the key, choose when the old key stops working (now, or in 1 hour, 24 hours or 7 days) and click **Rotate key**. The grace period lets you deploy the new key before the old one stops.

## Revoke a key

On the **API keys** tab, click **Revoke** next to the key, then **Revoke key**. Apps using the key stop working immediately; this can't be undone.

## Authentication errors

| Status | `error.code` | Meaning |
| - | - | - |
| 401 | `MISSING_CREDENTIALS` | No `Authorization: Bearer` header |
| 401 | `INVALID_CREDENTIALS` | The key is malformed or unknown |
| 401 | `CREDENTIALS_EXPIRED` | The key has expired; create a new one |
| 401 | `CREDENTIALS_REVOKED` | The key was revoked |
| 401 | `WRONG_ENVIRONMENT` | The key belongs to a different Revilico environment |
| 403 | `API_ACCESS_NOT_ENABLED` | API access isn't enabled for your organization |
| 403 | `ACCOUNT_INACTIVE` | Your account or organization is not active |
| 403 | `INSUFFICIENT_SCOPE` | The key lacks the scope this endpoint needs |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.