# Authentication

> An rst_ key in the Authorization header for your scripts, OAuth for agents. Never a key in an address.

## API keys

A key is created in [Settings › API keys](https://app.rustine.io/en/settings?section=apiKeys). It starts with `rst_`, works for your whole workspace and is shown only once: Rustine only keeps a fingerprint of it.

It goes **only** in the header:

```http
Authorization: Bearer rst_...
```

Never in the address (`?key=…`): a URL ends up in server logs, browser history and screenshots.

- One key per use ("CI", "n8n", "deploy script"): you know which one to revoke.
- A key has every permission of your workspace: read, scan, unlock a fix, mark an issue.
- Error messages and issue texts come in the language of the key's owner.
- If a key leaks, click **Revoke**: it stops working at once. Create another one.

## OAuth, for agents

Claude, ChatGPT, Claude Code, Cursor and VS Code connect to the [MCP server](https://docs.rustine.io/en/mcp/connect.md) with OAuth: no key to copy, you click **Allow** and the agent renews its access by itself. You see every connected agent in **Settings › Connected agents**, and disconnect it in one click.

The OAuth access token (`rat_…`) also works on the API, in the same header. It only has the permissions granted to the agent: every reference page says which one the route needs (`scans:read`, `scans:run`, `fixes:unlock` or `issues:write`). Without it, the answer is `403 scope_missing`.

## Requirements

- A plan that opens the API and MCP: Pro, or the Solo plan's trial ([Access](https://docs.rustine.io/en/access.md)).
- Two-factor authentication turned on in your Rustine account, to create a key or allow an agent.

## Refusals

| Status | `error.code` | What happens |
| --- | --- | --- |
| 401 | [`authentication_required`](https://docs.rustine.io/en/api/errors#authentication_required) | No key in the request. |
| 401 | [`invalid_api_key`](https://docs.rustine.io/en/api/errors#invalid_api_key) | Wrong, revoked or expired key. |
| 403 | [`scope_missing`](https://docs.rustine.io/en/api/errors#scope_missing) | The OAuth token lacks the permission. |
| 402 | [`api_plan_required`](https://docs.rustine.io/en/api/errors#api_plan_required) | The plan does not open the API. |

## Examples

### curl

```bash
curl https://api.rustine.io/v1/account \
  -H "Authorization: Bearer $RUSTINE_API_KEY"
```

### Response: 401 Unauthorized

```json
{
  "error": {
    "type": "authentication",
    "code": "invalid_api_key",
    "message": "This API key or token is invalid, revoked or expired.",
    "doc_url": "https://docs.rustine.io/api/errors#invalid_api_key"
  }
}
```