# Authenticating to name.ai

> This documents the OAuth 2.1 flow for the name.ai MCP server
> (https://name.ai/.well-known/mcp.json). All 4 MCP tools (domain search, WHOIS,
> TLD pricing/requirements) work without authentication. Signing in unlocks
> one additional thing: real marketplace prices instead of the "sign in to
> see pricing" placeholder every guest gets on the website.

## Flow

Standard OAuth 2.1, authorization_code grant, PKCE required (S256 only, no
client secret — every client is public).

1. **Register** — `POST https://name.ai/api/oauth/register` with
   `{"redirect_uris": ["<your-callback-url>"], "client_name": "<your app>"}`.
   Returns a `client_id`. No manual approval needed (RFC 7591 dynamic
   client registration).
2. **Authorize** — send the user's browser to:
   `https://name.ai/oauth/authorize?response_type=code&client_id=<id>&redirect_uri=<uri>&code_challenge=<s256-of-verifier>&code_challenge_method=S256&state=<random>`.
   They sign in (if needed) and approve. They land back at your
   `redirect_uri` with `?code=...&state=...`.
3. **Exchange** — `POST https://name.ai/api/oauth/token`
   (`application/x-www-form-urlencoded`) with
   `grant_type=authorization_code&code=<code>&redirect_uri=<uri>&client_id=<id>&code_verifier=<verifier>`.
   Returns `access_token`, `refresh_token`, `expires_in` (seconds),
   `token_type: "Bearer"`.
4. **Use it** — send `Authorization: Bearer <access_token>` on your MCP
   tool call (or on `POST https://name.ai/api/domain/search` directly if
   you're calling the REST API instead of MCP). `search_domain` will
   return real prices instead of hidden ones.
5. **Refresh** — `POST https://name.ai/api/oauth/token` with
   `grant_type=refresh_token&refresh_token=<refresh_token>` before the
   access token expires. Refresh tokens rotate on every use.

## Discovery

- Authorization server metadata (RFC 8414):
  `https://name.ai/.well-known/oauth-authorization-server`
- MCP server + capabilities: `https://name.ai/.well-known/mcp.json`
- REST API for the same endpoints: `https://name.ai/openapi.json`

## Notes

- Access tokens expire in 30 minutes; refresh tokens in 30 days.
- `redirect_uri` must exactly match what you registered — no exceptions.
- Authorization codes are single-use and expire in 60 seconds.
- No refresh-without-rotation: each refresh issues a new refresh token and
  invalidates the old one.