# Authentication

> API keys, project binding, and scopes.


All requests require a RavChat API key in the `Authorization` header:

```bash
Authorization: Bearer sk-rav-...
```

## Creating keys

<Steps>
  <Step title="Open key settings">
    Go to **app.rav.chat → Settings → API Keys**.
  </Step>
  <Step title="Create and copy the secret">
    The full secret is shown **exactly once** at creation. Store it immediately — afterwards only the prefix and last four characters are displayed.
  </Step>
</Steps>

<Warning>
Keys are stored hashed. Treat a key like a password: server-side use only, never in browser or mobile code, never committed to a repository. `sk-rav-` is fingerprinted by common secret scanners. Lost keys are revoked and reissued, never recovered.
</Warning>

## Project binding

By default every new key is **project-scoped**: bound to one RavChat project, able to see and touch only that project's sessions and files. If you don't pick a project at creation, RavChat creates a dedicated API project for the key on first use.

You may explicitly create an **owner-wide** key that can reach all projects you own. A key can never reach another user's resources under any configuration.

<Info>
Requests that reference a resource outside the key's binding receive **404** — the same response as for a resource that doesn't exist. Existence is never disclosed across scope boundaries.
</Info>

## Scopes

Each key carries a scope list, checked on every endpoint.

| Scope | Grants |
|---|---|
| `models:read` | `GET /v1/models` |
| `chat:write` | `POST /v1/chat/completions` |
| `sessions:write` | resuming sessions via `metadata.ravchat.session_id` |
| `files:read` | list / get / download files |
| `files:write` | upload and delete file objects |
| `projects:read` | list / get projects |
| `projects:write` | create projects |

Default scopes on new keys: `models:read`, `chat:write`, `sessions:write`, `files:read`, `files:write`, `projects:read`.

An operation on a **visible** resource without the required scope returns **403**. A resource outside the key's project binding returns **404**.

## Plan requirements

API access follows your RavChat plan — free-tier accounts cannot call the API. See [Errors & limits](/guides/errors-and-limits) for per-plan rate limits. All API usage bills RavChat credits from the same pools as the app.