# Authentication

> Personal API tokens for scripts, OAuth 2.1 for apps and MCP clients, and what each kind of token may do.

Every request sends a bearer token:

```http
Authorization: Bearer lyd_pat_...
```

Tokens work on the operation routes under `https://api.lydie.co/v1` and on the MCP server at
`https://api.lydie.co/mcp`. Everything else answers `401`.

## Personal API tokens

Use one for your own scripts and agents. Create it in **Settings → Agents & API → Hosted API**, or
with [Create an API token](https://developers.lydie.co/api/api-tokens/create-an-api-token.md) from a signed-in session.

- The secret is `lyd_pat_` followed by 43 characters. Lydie shows it once and stores only a hash.
- **Scopes:** `docs:read` lets the token read, and `docs:write` lets it make changes. New tokens get
  both unless you choose read only.
- **Expiry:** never, or after a number of days you choose.
- **Revoke** it in the same settings page. It stops working at once.

## What a token can do

A token acts as you, with your access to pages, and is limited to the workspace it was made for.

- Pages, teamspaces and members of other workspaces answer `404 not_found`, as if they did not exist.
- An operation needs the token's scope: queries need `docs:read` and changes need `docs:write`. A
  token without the scope gets `403 forbidden`.
- Some operations need a signed-in session in the Lydie app and refuse every token with `403`.
  These include managing tokens and connected apps, creating a workspace, transferring ownership,
  leaving a workspace, and accepting or declining invitations. The reference marks them.

Changes made with a token are recorded as an agent acting for you. The document's `createdBy` or
`updatedBy` reads `agent:api-token:<token id>:<your user id>`. See
[Agent changes and undo](https://developers.lydie.co/agent-history.md).

## OAuth 2.1

OAuth is for apps that act for other people, and for MCP clients. The person approves the app in
Lydie, picks a workspace, and can narrow the scopes. MCP clients that support the MCP authorization
spec do all of this themselves: give them `https://api.lydie.co/mcp` and they open the sign-in page.

| Step                 | Endpoint                                                                                       |
| -------------------- | ---------------------------------------------------------------------------------------------- |
| Discovery            | `GET /.well-known/oauth-protected-resource/mcp`, `GET /.well-known/oauth-authorization-server` |
| Register the client  | `POST /oauth/register` (RFC 7591, public clients), or a client ID metadata document URL        |
| Authorize            | `GET /oauth/authorize` with `response_type=code`, PKCE `S256` (required), `state`, `scope`     |
| Exchange and refresh | `POST /oauth/token` (`authorization_code`, `refresh_token`)                                    |
| Revoke               | `POST /oauth/revoke` (RFC 7009)                                                                |

All endpoints are on `https://api.lydie.co`. A request to `/mcp` without a token gets `401` with a
`WWW-Authenticate` header pointing at the discovery document.

- Scopes are the same as for API tokens: `docs:read docs:write`.
- Access tokens (`lyd_oat_…`) last one hour and have the same limits as API tokens.
- Refresh tokens (`lyd_ort_…`) last 30 days and rotate on every use. Reusing an old refresh token
  revokes the whole grant.
- Redirect URIs must be `https`, `http` on a loopback address (any port), or an app's own scheme.
- People see and disconnect apps under **Settings → Agents & API → Connected apps**.