# auth.md — Autenticación en Mercatren

## Resumen

- **Leer el catálogo no necesita credenciales.** `https://mercatren.com/datos/catalogo`, `https://mercatren.com/datos/buscar`, el servidor MCP `https://mercatren.com/datos/mcp` y las fichas en Markdown (`Accept: text/markdown`) son públicos.
- **La API de socios** (`https://mercatren.com/datos/socios/*`: cobros por enlace y sincronización de catálogo) usa un **token de tienda** como `Authorization: Bearer <token>`.
- **No hay servidor OAuth/OIDC.** No se publican `/.well-known/openid-configuration` ni `/.well-known/oauth-authorization-server` porque no existen; publicarlos sería mentir. El recurso protegido sí se describe en https://mercatren.com/.well-known/oauth-protected-resource.

## Cómo consigue un agente (o un comercio) su token

1. El comercio tiene que existir en Mercatren: se registra en https://mercatren.com/es/vender y crea su tienda.
2. El token de la tienda lo entrega el equipo de Mercatren al vincular la tienda con el sistema del comercio. Pídelo escribiendo a **hola@mercatren.com** con el nombre de la tienda y para qué se va a usar (cobros, catálogo o los dos).
3. Una **plataforma socia** (un sistema que opera muchas tiendas) obtiene el token de cada tienda con su llave de socio en `POST https://mercatren.com/datos/socios/vincular` (`{ "externo_id", "nombre", "slug_existente" }`).
4. Guarda el token en el servidor, nunca en el navegador. Se revoca desvinculando la tienda; para revocarlo o rotarlo, escribe a hola@mercatren.com.

## Identidades y credenciales admitidas

| Tipo de identidad | Credencial | Alcance |
| --- | --- | --- |
| Tienda (comercio) | Token de tienda (Bearer) | Sus cobros y su catálogo, nunca los de otra tienda |
| Plataforma socia | Llave de socio (Bearer) | Vincular tiendas y obtener sus tokens |
| Comprador | Sesión en el sitio (cookie) | Su cuenta, su carrito y sus pedidos |

## Especificación y skills

- OpenAPI: https://mercatren.com/datos/openapi.json
- Catálogo de la API (RFC 9727): https://mercatren.com/.well-known/api-catalog
- Skills: https://mercatren.com/.well-known/agent-skills/index.json
- Contacto: hola@mercatren.com

---

# auth.md (English)

## Audience

AI agents and merchant systems that want to read the Mercatren catalog (no credentials needed) or use the partner API (payment links and catalog sync) on behalf of a store that exists on Mercatren.

## Registration

- **Public reads need no registration.** `https://mercatren.com/datos/catalogo`, `https://mercatren.com/datos/buscar`, the MCP server `https://mercatren.com/datos/mcp` and Markdown pages (`Accept: text/markdown`) are open.
- **A store (merchant) registers** at https://mercatren.com/es/vender and creates its store. Its API token is provisioned by the Mercatren team when the store is linked to the merchant's system: email **hola@mercatren.com** with the store name and the intended use (payments, catalog, or both).
- **A partner platform** (a system operating many stores) provisions store tokens with its partner key: `POST https://mercatren.com/datos/socios/vincular` with `{ "externo_id", "nombre", "slug_existente" }` returns the store token.
- There is no self-service, automated agent registration endpoint and **no OAuth/OIDC authorization server**; the protected resource metadata at https://mercatren.com/.well-known/oauth-protected-resource lists no authorization servers on purpose.

## Credentials

- Type: **Bearer token** (store token or partner key), sent as `Authorization: Bearer <token>` on every request to `https://mercatren.com/datos/socios/*`.
- Scope: a store token only reaches that store's payment links and catalog; a partner key only links stores.
- Storage: keep it server-side, never in a browser or a public repository.

## Supported methods

| Identity | Credential | Method |
| --- | --- | --- |
| Store (merchant) | Store token | `Authorization: Bearer` header |
| Partner platform | Partner key | `Authorization: Bearer` header, then `POST /datos/socios/vincular` |
| Shopper | Site session (cookie) | Sign in at https://mercatren.com/en/entrar |

## Revocation and rotation

Tokens are revoked by unlinking the store. To revoke or rotate a token, email hola@mercatren.com.

## References

- OpenAPI: https://mercatren.com/datos/openapi.json
- Protected resource metadata (RFC 9728): https://mercatren.com/.well-known/oauth-protected-resource
- Skills: https://mercatren.com/.well-known/agent-skills/index.json