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

# OAuth

> Protocol details for MCP client builders

Dexi's MCP server is a full OAuth 2.1 authorization server. Off-the-shelf MCP clients handle all of this automatically — this page is for people building their own client or debugging a connection.

## Discovery

Standard metadata at the domain root:

```
https://mcp.dexi.net/.well-known/oauth-authorization-server   (RFC 8414)
https://mcp.dexi.net/.well-known/oauth-protected-resource     (RFC 9728)
```

Endpoints: `/authorize`, `/token`, `/register`, `/revoke`.

## Client registration

Dynamic client registration (RFC 7591) is open — `POST /register` with your metadata. Redirect URIs must match **exactly** and be either HTTPS or a localhost loopback (`localhost`, `127.0.0.1`, `[::1]`; any port). Client secrets are stored hashed.

## Authorization

* **PKCE S256 is required** on every authorization request.
* `/authorize` does not itself log the user in: it parks the request and redirects to Dexi's consent page (`app.dexi.net/account/authorize`), which is login-gated. On approval the user agent returns to your redirect URI with `code` + `state`; denial returns `error=access_denied`.
* Pending authorization requests expire after 10 minutes; authorization codes (`dxc_…`) expire after 5 minutes and are single-use — replaying one fails.

## Scopes

`notes:read` and `notes:write`. Both are valid and granted by default when unspecified; `notes:read` is the minimum every tool call requires. Request only what you need — the consent page shows the user exactly what was asked.

## Access restrictions

Beyond scopes, the consent page lets the user limit the connection to notes in one folder, notes with one tag, or both — and edit that choice later in **Settings → Connected apps**. Three properties matter to client builders:

* **Latest consent wins.** The restriction is stored per user + client, not per token. Re-authorizing the same client replaces the previous restriction, and the new boundary governs every outstanding token for that client.
* **Edits apply live.** The boundary is re-read on every request, so a settings change takes effect on the connection's next call — no token refresh or re-authorization involved.
* **Folder deletion fails closed.** If the restricted folder is deleted, the connection loses all access (every tool call errors with an explanation) until the user edits or disconnects it. Access never silently widens.

Under any restriction the connection sees only the user's own notes; [tool behavior inside a boundary](/mcp/tools#access-restrictions) is documented per tool.

## Tokens

| Token   | Prefix | Lifetime   |
| ------- | ------ | ---------- |
| Access  | `dxm_` | 60 minutes |
| Refresh | `dxr_` | 30 days    |

Tokens are opaque (not JWTs) and stored hashed server-side. **Refresh rotation is strict**: exchanging a refresh token revokes that token *and* every outstanding access token for the same client + user. Don't reuse old refresh tokens; store the new pair from each refresh response.

## Revocation

* RFC 7009 `POST /revoke` — revoking either token kind kills the entire grant for that client + user.
* Users can disconnect any client in **Settings → Connected apps**, with the same effect. Expect calls to start failing with 401 at any time; re-run the authorization flow to reconnect.

## Compatibility note

`https://api.dexi.net/mcp` serves the same server (one service, two domains) and remains supported for connections created before the `mcp.dexi.net` domain existed. Use `mcp.dexi.net` for anything new.