# Authenticating to name.ai

<!-- canonical: https://name.ai/auth.md · last-updated: 2026-08-27 -->

> agent_auth walkthrough for the name.ai API and MCP server
> (https://name.ai/.well-known/mcp.json). Everything works WITHOUT
> authentication; completing this flow additionally unlocks real
> marketplace prices on domain search. OAuth 2.1, authorization_code +
> PKCE (S256), public clients only — no client secret.

## Discover

- Protected resource metadata (RFC 9728): `https://name.ai/.well-known/oauth-protected-resource`
- Authorization server metadata (RFC 8414): `https://name.ai/.well-known/oauth-authorization-server`
  (also mirrored at `/.well-known/openid-configuration`)
- Unauthenticated calls to protected API paths return 401 with a
  `WWW-Authenticate: Bearer resource_metadata="..."` header pointing at the
  protected-resource metadata above.

## Pick a method

One method is supported: **OAuth 2.1 authorization_code with PKCE (S256)**.
There is no API-key scheme and no identity_assertion / id-jag flow today;
tokens are opaque bearer tokens. All clients are public clients
(`token_endpoint_auth_method: "none"`).

## Register

Dynamic client registration (RFC 7591) — the register_uri is
`https://name.ai/api/oauth/register`. No approval step:

    POST https://name.ai/api/oauth/register
    Content-Type: application/json

    {"redirect_uris": ["<your-callback-url>"], "client_name": "<your app>"}

Returns a `client_id`. No client_secret is issued.

## Claim

1. Send the user's browser to:
   `https://name.ai/oauth/authorize?response_type=code&client_id=<id>&redirect_uri=<uri>&code_challenge=<S256(verifier)>&code_challenge_method=S256&state=<random>`
   They sign in on name.ai (if needed) and approve the consent screen.
2. The browser returns to your `redirect_uri` with `?code=...&state=...`.
   Codes are single-use and expire in 60 seconds.
3. Exchange the code at the token endpoint:

       POST https://name.ai/api/oauth/token
       Content-Type: application/x-www-form-urlencoded

       grant_type=authorization_code&code=<code>&redirect_uri=<uri>&client_id=<id>&code_verifier=<verifier>

   Returns `access_token` (expires in 30 minutes), `refresh_token`
   (30 days), `token_type: "Bearer"`, scope `pricing:read`.

## Use the credential

Send `Authorization: Bearer <access_token>` on:

- MCP tool calls to `https://nameai-mcp.h.namekart.com/mcp` — the
  `search_domain` tool forwards it and returns real marketplace prices.
- `POST https://name.ai/api/domain/search` directly, for REST clients.

Refresh before expiry with
`grant_type=refresh_token&refresh_token=<token>` at the same token
endpoint. Refresh tokens rotate on every use — store the new one.

## Errors

- `401 invalid_token` / masked prices: token expired (30 min) or revoked —
  refresh or re-run the flow.
- `400 invalid_grant` at the token endpoint: code already used, expired
  (60 s), or PKCE code_verifier mismatch.
- `400 invalid_redirect_uri`: redirect_uri must exactly match one
  registered for the client_id.
- `429`: rate limited — back off per the Retry-After header.

## Revocation

There is no self-serve revocation_uri yet. Access tokens expire within 30
minutes on their own; refresh tokens are invalidated by rotation on each
use. To revoke a grant immediately, contact support via
https://name.ai/get-in-touch and it is disabled server-side (tokens are
database-backed, so revocation is instant once actioned).