> For AI assistants: read [llms.txt](https://docs.saturation.io/llms.txt) first for the complete documentation map, API contract, and endpoint Markdown files.

# Authentication

The API authenticates with a personal token sent in the `Authorization` header. Create one in Saturation under Settings > Developers > API.

```
Authorization: Bearer <token>
```

A token belongs to one workspace and carries the access level of the user it was issued to.

## Create and revoke a token

Create and revoke tokens in the web app, at Settings > Developers > API.

- **Create.** Name the token, then copy the secret. The token binds to the workspace you create it in. The secret is shown once.
- **Revoke.** Takes effect on the token's next call. The API then rejects it with `401 token_revoked`.

Use `GET /me` to test a token and see which workspace it can access.

## Confirm who a token is

Call `GET /v1/me` to confirm the account and workspace.

```bash
curl https://next-api.saturation.io/v1/me \
  -H "Authorization: Bearer $SATURATION_TOKEN"
```

```json
{
  "id": "usr_4f1a8c2e",
  "type": "user",
  "email": "producer@example.com",
  "name": "Dana Producer",
  "workspaces": [
    { "workspaceId": "ws_2b9d7a1f", "workspaceRole": "admin" }
  ]
}
```

`workspaces` contains the token's workspace and your role in it. Other paths start with the item you want to use.

```bash
# Projects in the token's workspace
curl "https://next-api.saturation.io/v1/projects" \
  -H "Authorization: Bearer $SATURATION_TOKEN"
```

To work in a different workspace, create a token there.

## Common auth errors

| Status | Code | Meaning |
|---|---|---|
| `401` | `unauthenticated` | No credentials resolved. |
| `401` | `missing_authorization` | No `Authorization` header. |
| `401` | `invalid_token` | Malformed or expired token. |
| `401` | `token_revoked` | The token was revoked. |
| `403` | `permission_revoked` | Your access no longer permits this action. Carries a `requiredAbility` hint, e.g. `update:Transaction`. |

All error codes and response fields are listed in [Errors](/errors.md).

## Next

- [Concepts](/concepts.md): workspaces, short names, and the Library.
- [Errors](/errors.md): error responses and codes.
- [Pagination](/pagination.md): `limit` caps at 100, then page with `cursor`.