# nowyourlink auth.md

## Discover
Public reads need no credentials: GET https://nowyourlink.com/api/v1/spotlight, /api/v1/spotlights, /api/v1/spotlights/{day}, and the MCP server at https://nowyourlink.com/mcp. Advertiser actions need a delegated OAuth 2.1 token. Resource metadata: https://api.nowyourlink.com/.well-known/oauth-protected-resource. Authorization-server metadata: https://api.nowyourlink.com/.well-known/oauth-authorization-server, mirrored at https://nowyourlink.com/.well-known/oauth-authorization-server for a client that resolves it from the resource's own host. The same document plus the agent_auth block (anonymous identity, claim ceremony = OAuth consent) is at https://api.nowyourlink.com/.well-known/oauth-authorization-server-agent.

## Pick a method
Agents use the authorization-code flow with PKCE S256. Register with a Client ID Metadata Document (client_id = the https URL of your metadata JSON) or with dynamic client registration at https://api.nowyourlink.com/oauth/register. Scopes: account:read, bids:read, bids:write, creatives:read, creatives:write, invoices:read.

## Register
The advertiser must already have a nowyourlink account with a saved payment method (one bid placed in the browser). Registration, VAT validation, identity checks and payment setup are browser steps; an agent cannot complete them.

## Claim
Send the user to https://api.nowyourlink.com/oauth/authorize with response_type=code, client_id, redirect_uri, scope, state, code_challenge, code_challenge_method=S256. The user signs in at https://nowyourlink.com, reviews the scopes, and for bids:write sets a mandate: maximum single bid, daily cap, validity (max 90 days).

## Exchange
POST https://api.nowyourlink.com/oauth/token with grant_type=authorization_code, code, code_verifier, client_id, redirect_uri. Access tokens last 1 hour; refresh tokens 30 days and never beyond the mandate's valid_until.

## Use the access_token
Authorization: Bearer <token> on https://api.nowyourlink.com/v1/agent/* and on the advertiser MCP server https://api.nowyourlink.com/mcp. Idempotency-Key is required on bid requests. A walkthrough with sequence and flow diagrams is at [https://nowyourlink.com/blog/en/advertiser-mcp-server](https://nowyourlink.com/blog/en/advertiser-mcp-server).

## Errors
401 with WWW-Authenticate: Bearer resource_metadata="https://api.nowyourlink.com/.well-known/oauth-protected-resource" when the token is missing or invalid. Agent errors are application/problem+json with a code: agent.scope-missing, agent.mandate-exceeded, agent.mandate-expired, agent.human-step-required (with action_url), agent.idempotency-key-required.

## Revocation
Clients revoke a token at https://api.nowyourlink.com/oauth/token (RFC 7009; it is the revocation_endpoint the authorization-server metadata advertises). Advertisers revoke a whole grant in the browser at https://nowyourlink.com/app/agents. Revoked tokens fail with 401 invalid_token on the next request.