# Coupondroid Chile auth.md

How AI agents authenticate with Coupondroid Chile (https://coupondroid.cl/).

## Who needs credentials

- **Public agent APIs: no authentication.** The public MCP server (https://coupondroid.cl/mcp/public) and the A2A agent
  (https://coupondroid.cl/a2a, card at https://coupondroid.cl/.well-known/agent-card.json) are read-only and open to any agent. Just call them
  (limit: 120 requests per minute per IP). There is nothing to register.
- **Management MCP server (https://coupondroid.cl/mcp): team only.** It reads and writes the website's content with the
  permissions of a person of the Coupondroid Chile team. Agents cannot create accounts or register on their own:
  every token belongs to a team member who signed in and approved the connection.

## 1. Discover

1. `GET https://coupondroid.cl/.well-known/oauth-protected-resource` (RFC 9728): the resource is `https://coupondroid.cl/mcp`, the
   authorization server is `https://coupondroid.cl`, the scopes are `read`, `write` and `delete`, and the token goes in the
   `Authorization: Bearer` header.
2. `GET https://coupondroid.cl/.well-known/oauth-authorization-server` (RFC 8414): endpoints and supported flows.
3. A request to `https://coupondroid.cl/mcp` without a token answers `401` with
   `WWW-Authenticate: Bearer resource_metadata="…"` pointing to the document of step 1.

## 2. Register the client

`POST https://coupondroid.cl/oauth/register` (OAuth 2.0 Dynamic Client Registration, RFC 7591) with your `client_name` and
`redirect_uris`. Public clients use `token_endpoint_auth_method: "none"`. Registering a client does not
give access to anything by itself.

## 3. Get a token on behalf of a team member

Authorization code flow with PKCE (`S256` only):

1. Send the person to `https://coupondroid.cl/oauth/authorize` with `response_type=code`, your `client_id`,
   `redirect_uri`, `scope`, `state`, `code_challenge` and `code_challenge_method=S256`.
2. The person signs in with their team account (password and, if enabled, a 2FA code) and approves the
   connection. If your `redirect_uri` is not on a well-known AI client, they must also type its host to
   confirm, to stop phishing.
3. Exchange the code at `https://coupondroid.cl/oauth/token` (`grant_type=authorization_code`, with the `code_verifier`).
   Refresh with `grant_type=refresh_token`; revoke at `https://coupondroid.cl/oauth/revoke`.

## 4. Use the credentials

Send `Authorization: Bearer <access_token>` on every request to `https://coupondroid.cl/mcp`. What a token can do is the
smaller of its scopes and the role of the person behind it. The person can see and revoke connections
at `https://coupondroid.cl/oauth/connections`.

## Errors

- `401` with `WWW-Authenticate`: missing, expired or revoked token. Refresh it or restart step 3.
- `403` / `forbidden`: the scope or the person's role does not allow that action.
- `429` / `rate_limited`: slow down and retry later.