# Scopes

A key can call an endpoint only when it holds that endpoint's **scope**.
Scopes are Muvia's own permission names — the same ones a role grants a
person, such as `datasets_read`. They are chosen when the key is issued, and an
administrator can change them later without changing the key's value.

## Scope per endpoint

| Endpoint | Scope |
| --- | --- |
| `GET /v1/company` | `settings_read` |
| `GET /v1/projects`, `GET /v1/projects/{project_id}` | `settings_read` |
| `GET /v1/projects/{project_id}/datasets`, `GET /v1/projects/{project_id}/datasets/{dataset_id}` | `datasets_read` |
| `GET /v1/projects/{project_id}/datasets/{dataset_id}/rows` | `datasets_read` |
| `GET /v1/projects/{project_id}/nodes`, `GET /v1/projects/{project_id}/nodes/{node_id}` | `nodes_read` |
| `GET /v1/whoami` | none: any valid key |

A key that reads everything v1 offers needs `settings_read`, `datasets_read`
and `nodes_read`. Grant only what the integration uses.

Through the [MCP server](/guides/mcp-server) the same scopes gate the tools, and a
write also needs the key to be allowed to write through assistants.

Calling an endpoint without its scope answers 403:

```json
{
  "error": {
    "code": "forbidden",
    "message": "The API key does not grant the required scope",
    "status": 403
  }
}
```

## Who can grant what

An administrator can grant a key only scopes they hold themselves, both when
issuing it and when changing it later. `superadmin` can never be granted to a
key.

## Modules cap every key

A company's enabled modules cap every key, on every request. A scope that
belongs to a module the company has switched off is taken out of the key for
as long as the module stays off, and the endpoints that need it answer 403.
The key itself stays valid and keeps its other scopes; switching the module
back on gives the scope back.

The three scopes v1 uses belong to Muvia's core, which is always on, so today
no module switch removes them. The rule holds for every scope the API adds
later.

## One company per key

A key sees the company that issued it and nothing else. A project, dataset or
node of another company answers 404, exactly like one that does not exist: the
API never confirms that data outside your company exists.
