Conectar con OAuth

Para los clientes que descubren el servidor solos: no les pegás ninguna llave, les das la dirección y ellos te mandan a una pantalla de Riverz a decir que sí.

Si tu cliente sabe mandar una cabecera Authorization, no necesitás nada de esto — la vía de la llave es más corta. Esto es para conectores que esperan un servidor de autorización del otro lado.

Lo que pasa, en orden

• Tu cliente llama a https://riverz.co/api/mcp sin credencial y recibe un 401 con un WWW-Authenticate que apunta al documento de descubrimiento.
• De ahí saca el servidor de autorización y se registra solo en /api/oauth/register. Nadie de Riverz tiene que crear nada a mano.
• Te abre /oauth/autorizar. Ahí ves quién pide acceso, a qué cuenta y qué va a poder hacer. Si no tenés sesión, primero entrás y volvés a la misma pantalla.
• Le das Autorizar y el cliente recibe un código, que canjea por un token en /api/oauth/token.

Los documentos de descubrimiento

GET https://riverz.co/.well-known/oauth-protected-resource
GET https://riverz.co/.well-known/oauth-authorization-server

Los dos son públicos: describen cómo pedir permiso, no dan ninguno.

Detalles que importan si lo implementás a mano

PKCE es obligatorio, y sólo S256

No hay secreto de cliente. Como los clientes se registran solos, el client_id no prueba nada: lo que ata el canje a quien pidió el código es el code_verifier. Un code_challenge_method que no sea S256 se rechaza.

Las redirecciones se comparan exactas

Tienen que ser una de las que registraste, carácter por carácter. Sin prefijos ni comodines — aceptar “empieza con” es exactamente cómo se roban códigos de autorización. Se admite https, y http sólo en localhost, porque un cliente de escritorio no tiene cómo tener un certificado.

Los alcances

• mcp:read — consulta y no cambia nada.
• mcp:write — además puede actuar. Sigue pidiendo confirmación para lo irreversible.

Si no pedís ninguno, se concede el más chico. Un cliente que no dijo qué necesita no necesita escribir.

El token vence en una hora

A propósito: si se filtra, la ventana es corta. Con el refresh_token sacás otro sin volver a molestar a nadie.

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

grant_type=refresh_token&refresh_token=...&client_id=...