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

# Scopes

> Every scope you can request and the access each one grants

Scopes control what an access token can do. Request the smallest set your app needs. In the
authorization code flow the user sees these scopes on the consent screen and approves them.

Pass scopes as a space separated string in the `scope` parameter, or as an array to the SDK.

```
scope=profile:read workspaces:read models:read
```

## Reference

| Scope              | Grants                                           |
| ------------------ | ------------------------------------------------ |
| `profile:read`     | Read the account of the user who approved access |
| `workspaces:read`  | List and view workspaces                         |
| `workspaces:write` | Create and update workspaces                     |
| `members:read`     | View workspace members                           |
| `members:write`    | Manage members and invitations                   |
| `providers:read`   | View providers                                   |
| `providers:write`  | Create, update, and delete providers             |
| `models:read`      | View models and configs                          |
| `models:write`     | Create, update, and delete models                |
| `prompts:read`     | View prompts                                     |
| `prompts:write`    | Create, update, and delete prompts               |
| `mapping:read`     | View model mappings                              |
| `mapping:write`    | Create, update, and delete mappings              |
| `keys:read`        | List API keys                                    |
| `keys:write`       | Create and update API keys                       |
| `usage:read`       | View usage and metrics                           |
| `quotas:read`      | View quota rules                                 |
| `quotas:write`     | Create, update, and delete quotas                |

## Read the profile

`profile:read` is the scope that answers "who approved access". With it, a token can call
`GET /api/v1/user` and read the account.

```json theme={null}
{
  "data": {
    "id": "3f0e...",
    "email": "user@example.com",
    "username": "user",
    "role": "USER",
    "account_type": "PERSONAL",
    "plan": "pro",
    "email_verified": true,
    "created_at": "2026-01-04T10:22:00.000Z"
  }
}
```

The response never includes secrets such as passwords, tokens, or two factor material.

## Sensitive scopes

<Warning>
  `keys:write` lets an app mint gateway API keys, and `members:write` lets an app manage who
  belongs to a workspace. Request them only when the app truly needs them, and expect users to
  scrutinize them on the consent screen.
</Warning>

## How scopes are enforced

A request must satisfy two checks. The token must carry the scope, and the account must have
permission for the action. If either fails the API returns `403`. If the token is missing or
expired the API returns `401`.

The token is limited to the intersection of the scopes the user approved and the scopes the
application currently holds. Narrowing an application's scopes narrows every token it issued.