# Authenticate API Requests

> Send authenticated requests to the Done Bear API with a JWT or API key.

Authenticate requests to the Done Bear API with a bearer token or API key.

## Send a bearer header

Every API request uses the same header shape:

```bash
curl https://api.donebear.com/graphql \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  --data '{"query":"query { viewer { id email } }"}'
```

## Use a CLI-created API key for automation

Create a key from the CLI, or mint one during agent signup:

```bash
donebear auth signup --email person@example.com --json --no-interactive
donebear api-key create "CI"
```

Then export it:

```bash
export DONEBEAR_TOKEN=<db_key>
curl https://api.donebear.com/graphql \
  -H "Authorization: Bearer $DONEBEAR_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"query":"query { myWorkspaces { id name } }"}'
```

API keys are the recommended credential for CI jobs and long-lived integrations.

## Scoped permissions

API keys carry one of three scopes. Ask for the least that does the job.

| Scope   | Use it for                                                       |
| ------- | ---------------------------------------------------------------- |
| `read`  | Listing and showing tasks, projects, labels, and teams           |
| `write` | Creating and editing those records (`read` is included)          |
| `admin` | Workspaces, billing, members, and API keys (`write` is included) |

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

MCP OAuth advertises `read` and `write`. See [API scopes](/api/scopes) and the [OpenAPI specification](https://donebear.com/openapi.json).

## Use a JWT for user-scoped requests

The API also accepts Supabase JWTs as bearer tokens. Use the same `Authorization: Bearer <jwt>` header. This is the credential type the CLI's interactive OAuth flow uses.

## Common auth errors

| Response                                        | Meaning                             | Fix                                        |
| ----------------------------------------------- | ----------------------------------- | ------------------------------------------ |
| `401 {"error":"Authorization header required"}` | You did not send a bearer header    | Add `Authorization: Bearer <token>`        |
| `401 {"error":"Invalid authorization format"}`  | The header is not `Bearer ...`      | Fix the header format                      |
| `401 {"error":"Invalid API key"}`               | The `db_` key is invalid or revoked | Create a new key or use another credential |
| `401 {"error":"Invalid token"}`                 | The JWT is invalid                  | Refresh the token or sign in again         |

## Next steps

- Read [GraphQL reference](/api/graphql) for queries and mutations.

---

Every Done Bear page is listed at https://donebear.com/llms.txt. Any page has a markdown copy at its URL plus `.md`. Start from the map rather than guessing a path.