# API scopes

> Scoped permissions for Done Bear API keys and MCP OAuth — read, write, and admin.

Done Bear API credentials are scoped so an agent can request only the access it needs.

## Scopes

| Scope   | What it covers                                                       | Implies         |
| ------- | -------------------------------------------------------------------- | --------------- |
| `read`  | List and show tasks, projects, labels, teams, and workspace metadata | —               |
| `write` | Create and edit tasks, projects, labels, and checklists              | `read`          |
| `admin` | Workspaces, billing, members, and API keys                           | `write`, `read` |

API keys accept all three. The hosted MCP OAuth flow advertises `read` and `write`.

## How to request a scope

Create a key from the CLI:

```bash
donebear api-key create "CI" --permissions read-only
donebear api-key create "Agent" --permissions full-access
```

`read-only` issues `read`. `full-access` issues `read`, `write`, and `admin`.

MCP clients request scopes during OAuth. Ask for `read` when the job is listing and showing; add `write` only when the agent must create or edit.

## Where scopes are enforced

- **MCP tools.** Read-only tools accept `read`. Tools that change data require `write`.
- **GraphQL.** Workspace, billing, and API-key mutations require `admin`.
- **OpenAPI.** Each operation lists the scopes it needs under `security`.

See the [OpenAPI specification](https://donebear.com/openapi.json) for the machine-readable catalog.

## Next steps

- [Authenticate API requests](/api/authentication)
- [GraphQL reference](/api/graphql)
- [MCP get started](/mcp/get-started)