# auth.md

Guía de autenticación para agentes de IA que quieran usar QuienDaMenos (https://quiendamenos.com).

## Audiencia

Agentes, bots y scripts que actúan **en nombre de un humano real** con cuenta en QuienDaMenos. No hay cuentas de agente separadas: una persona = una cuenta = un saldo. El agente es un cliente HTTP más de esa cuenta.

## Método de autenticación

- Tipo: API key personal (bearer token). No hay OAuth ni OpenID Connect; por eso no se publican `/.well-known/oauth-authorization-server` ni `/.well-known/oauth-protected-resource`.
- Header: `Authorization: Bearer qdm_live_<32 caracteres>`
- Alcance: toda la API en `https://api.quiendamenos.com` y el MCP remoto en `https://quiendamenos.com/mcp`. Para SSE con `EventSource` (sin headers) se acepta `?token=<key>`.
- Endpoints públicos sin key: `GET /auctions`, `GET /auctions/{id}`, `GET /auctions/{id}/leaderboard`, `GET /prizes/{id}/history`, `GET /health`.

## Cómo se obtiene una credencial

1. El humano crea su cuenta en https://quiendamenos.com (gratis) y verifica el email. El alta de cuentas por API está discontinuado: `POST /signup/agent` responde 410.
2. En https://quiendamenos.com/mi-cuenta → Seguridad → API key, genera la key. Se muestra **una sola vez**.
3. El humano se la entrega al agente (variable `QDM_API_KEY` para el MCP de npm, o el header Authorization para HTTP y para https://quiendamenos.com/mcp).

## Ciclo de vida

- Hay **una sola key activa por cuenta**. Generar otra revoca la anterior al instante.
- `401` con `{"code":"key_disabled"}` = la key fue revocada por una nueva; pedirle al humano la nueva.
- Un agente **no puede** generar ni rotar keys con su propia key: `POST /me/api-keys` responde `403 api_key_cannot_rotate`.
- Revocación: `DELETE /me/api-keys/{id}` o desde la web.
- Metadatos de la key activa (sin la key): `GET /me/api-keys`.

## Errores

Todas las respuestas de error son JSON: `{"error": "...", "code": "...", "hint": "..."}`. Las acciones de juego (ofertas, ayudas, bombas) devuelven además un objeto discriminado por `kind` en 200 y en 4xx.

## Referencias

- OpenAPI: https://quiendamenos.com/openapi.json
- Documentación: https://quiendamenos.com/docs/api
- MCP server card: https://quiendamenos.com/.well-known/mcp/server-card.json
- Guía para modelos: https://quiendamenos.com/llms.txt