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

# Authentication

> Scopes, repository-level access, and auth errors for the Mesa MCP server.

[Connect a client](/content/reference/mcp/connect) covers setup, OAuth or an API key, per client. This page covers what a credential can do once connected.

## Scopes and repository access

Every tool requires one of three access levels. The levels are hierarchical: `admin` includes `write`, and `write` includes `read`.

| Scope   | Grants                                                                                                             |
| ------- | ------------------------------------------------------------------------------------------------------------------ |
| `read`  | View repositories, changes, commits, content, and diffs.                                                           |
| `write` | Everything in `read`, plus creating changes, writing files, and creating, moving, merging, and deleting bookmarks. |
| `admin` | Everything in `write`, plus API key and webhook management.                                                        |

The **Access** column in the [Tool reference](/content/reference/mcp/tools) shows the scope each tool needs.

How far a credential reaches depends on how you signed in:

* **OAuth tokens** are granted to your user within an organization and carry full access to that organization.
* **API keys** can additionally be **scoped to specific repositories**. Tool calls targeting any other repository are rejected. This is the way to give an agent least-privilege access. See [Authentication](/content/concepts/authentication) for key management.

## Errors

A missing or invalid credential returns `401 Unauthorized` with a `WWW-Authenticate` header pointing back at the metadata, so a client can re-discover and re-authenticate:

```http theme={null}
WWW-Authenticate: Bearer realm="mesa", resource_metadata="https://api.mesa.dev/.well-known/oauth-protected-resource/mcp"
```

Error responses carry a stable code:

```json theme={null}
{
  "error": { "code": "UNAUTHENTICATED", "message": "Bearer token required" }
}
```

Server errors (5xx) additionally include `error.trace_id` — quote it when reporting an issue.