# auth.md — how an agent gets access to DoneOnce

DoneOnce has two MCP servers. Only one needs authentication.

| Server | URL | Authentication |
|---|---|---|
| DoneOnce Help MCP | `https://doneonce.app/mcp` | None. It is public and read-only: the help articles, prices and what DoneOnce is. |
| DoneOnce MCP | `https://mcp.doneonce.app/mcp` | OAuth 2.1, below. It reads and changes one business's data, as one of its people. |

## The DoneOnce MCP

The protected resource and its authorization server live on `mcp.doneonce.app`, so their metadata is
published there, not here:

- Protected resource metadata (RFC 9728): `https://mcp.doneonce.app/.well-known/oauth-protected-resource`
- Authorization server metadata (RFC 8414): `https://mcp.doneonce.app/.well-known/oauth-authorization-server`
- An unauthenticated request to `https://mcp.doneonce.app/mcp` answers `401` with
  `WWW-Authenticate: Bearer resource_metadata="…"`, the standard MCP discovery path.

### Registering an agent

1. **Register the client dynamically** (RFC 7591) at `https://mcp.doneonce.app/register`. Public
   clients only: `token_endpoint_auth_method` is `none`.
2. **Authorize with the code flow and S256 PKCE** at `https://mcp.doneonce.app/authorize`.
3. **A person approves.** A DoneOnce user signs in with their own account and presses **Approve**.
   The agent then acts as that person, with that person's role and permissions. The server re-checks
   them on every request, so a role change takes effect on the next call.
4. **Exchange the code** at `https://mcp.doneonce.app/token`.

No identity is issued to an agent on its own. Every connection belongs to a person in one business.

### Starting a new business from an assistant (device flow)

When the person has no DoneOnce account yet, or the assistant cannot receive a redirect, use the
device authorization grant (RFC 8628). The assistant never creates the account. The person does.

1. **Register as a device client** at `https://mcp.doneonce.app/register` with
   `grant_types: ["urn:ietf:params:oauth:grant-type:device_code"]` and no `redirect_uris`. A device
   client can use only this grant.
2. **Start** with `POST https://mcp.doneonce.app/device_authorization` (`client_id`, form-encoded).
   The answer has `device_code`, `user_code` (shown as `XXXX-XXXX`), `verification_uri`
   (`https://app.doneonce.app/device`), `verification_uri_complete`, `expires_in` and `interval`.
   Keep `device_code` to yourself. Show the person the link and the code.
3. **The person signs up or signs in on DoneOnce, checks the code and approves.** The connection then
   acts as that person, with that person's role and permissions.
4. **Poll** `POST https://mcp.doneonce.app/token` with
   `grant_type=urn:ietf:params:oauth:grant-type:device_code`, `device_code` and `client_id`, no faster
   than `interval` seconds. The answers are the RFC's:
   - `authorization_pending`: the person has not decided yet. Keep polling.
   - `slow_down`: you polled too fast. Add 5 seconds to your interval.
   - `access_denied`: the person said no. Stop.
   - `expired_token`: the 30 minutes ran out. Start again.
   - `invalid_grant`: the code is unknown, belongs to another client or was already used.
   - `temporarily_unavailable` (503): DoneOnce could not answer. Try again shortly.
   - Success: `access_token`, `token_type: "Bearer"` and `expires_in`.

A code lives **30 minutes** and can be approved once.

Connecting is not approval of anything else. Imports, money and messages to customers still go
through the person's own yes inside the conversation, tool by tool.

### Without OAuth

A program that can only send a fixed header can use a token instead. In DoneOnce, the person opens
**Settings → AI assistants → How to connect → With a token**, mints one, and the program sends it as
`Authorization: Bearer <token>`.

### Lifetime and revocation

- A connection lasts **90 days**; after that the person approves again.
- **Settings → AI assistants** lists every connection with when it was last used. **Revoke** ends one at
  once. Reconnecting the same assistant replaces its previous connection.

## More

- How a person connects Claude, ChatGPT or Claude Code: https://doneonce.app/help/agents
- What DoneOnce is and what an agent may state about it: https://doneonce.app/llms.txt
