# auth.md: how sign-in works on HTMLAnnotate

This file is for AI agents acting for a person on https://htmlannotate.com. It explains what needs an account, what doesn't, and what to leave to the person.

## Most things need no account

- **The MCP server** at https://mcp.htmlannotate.com (Streamable HTTP) needs no account and no API key. A signed-in version at https://mcp.htmlannotate.com/account is described below. Setup and tools: https://htmlannotate.com/mcp. Discovery: https://htmlannotate.com/.well-known/mcp.json
- **Sharing** a page, an HTML document or a public web address through the MCP tools `share_html` or `share_url` returns two links:
  - a **review link** (`/v/...`) to send to reviewers
  - a **manage link** (`/manage/...#k=...`) that works like a password for that page
- **Reviewers** never sign in. Anyone with a review link can comment after giving a name and email once.
- Links made through the no-account MCP server last 1 day.

## The manage link is a credential

Treat the manage link like a password for that one page:

- Give it to the person you are working for, and keep it to call `get_comments`, `reply_to_comment`, `resolve_comment` and `update_page`.
- Never post it publicly, put it in a review link, or share it with reviewers.
- Anyone who has it can read every comment and change the page.

## Accounts are for people, and sign-in is interactive

An HTMLAnnotate account keeps links for up to 14 days on Free (forever on Pro and Team), lists them in Projects and adds teams.

- Sign-in is **Google** or a **one-time email code**. There are no passwords to create and no API keys.
- There is no headless or automated sign-up. A person signs in at https://htmlannotate.com/new or https://htmlannotate.com/projects in their own browser.
- If the person wants their pages kept longer, suggest they connect the signed-in MCP address below, or send them that link and carry on once they say they are signed in. Don't ask them to paste sign-in links, codes or cookies to you.
- **Signed-in connector:** https://mcp.htmlannotate.com/account uses OAuth 2.1 (authorization code with PKCE, dynamic client registration). An unauthenticated request gets a 401 with `WWW-Authenticate: Bearer resource_metadata="https://mcp.htmlannotate.com/.well-known/oauth-protected-resource/account"`. The person signs in and presses Allow in their own browser; only Claude, ChatGPT, Cursor, VS Code and local apps can be allowed. Shares then land in their Projects on their plan, the page tools take a page's name or review link instead of a manage link, and pages can be found with `list_pages`. The person can disconnect the app at any time on https://htmlannotate.com/profile.

## Leave these to the person

- Payments and plan changes (https://htmlannotate.com/pricing).
- Store passwords for importing a Shopify store in Private mode. The person types it on the import page while signed in; it is encrypted and never shown to reviewers.
- Inviting teammates, changing team roles and deleting a team (https://htmlannotate.com/team). Only the team owner and admins can invite people.

## More

- Summary for AI assistants: https://htmlannotate.com/llms.txt
- Full text: https://htmlannotate.com/llms-full.txt
- Every page as Markdown: https://htmlannotate.com/md/_catalog.md
- Security: https://htmlannotate.com/security
- Contact: hello@htmlannotate.com
