# Auth.md — Autenticación e integraciones de Amautix

## Ayuda pública

GET https://amautix.com/agent-api/resources y el MCP https://amautix.com/mcp ofrecen solo lectura pública, sin credenciales. No envíes cookies ni contraseñas. El presupuesto conjunto es 600 solicitudes por minuto y proceso; 429 incluye Retry-After: 60. MCP admite cuerpos de hasta 16 KiB.

## Identidad de las personas

Amautix usa cuentas y sesiones propias y actúa como cliente de Google, Facebook y Microsoft cuando están configurados. Esta instancia opera además un servidor de autorización aislado para agentes, basado en oidc-provider 9.13.3. Es independiente de los proveedores sociales y solo autoriza ayuda pública. Los roles y las membresías escolares se validan en el servidor.

## Acceso delegado

El recurso delegado es https://amautix.com/agent-api/authorized-help. Emisor verificado: https://amautix.com (coincidencia exacta).

El operador registra clientes con la herramienta privada de aprovisionamiento, tras verificar el nombre del integrador y su redirect_uri HTTPS exacto. No hay registro abierto de clientes OAuth. El consentimiento requiere una sesión vigente de profesor, padre o administrador; las cuentas de alumnos no se vinculan. La identidad comunicada es seudónima, sin nombre ni correo. Usa authorization_code con PKCE S256, state impredecible, redirect_uri previamente registrado y resource=https://amautix.com/agent-api/authorized-help. Autoriza en https://amautix.com/agent-auth/authorize, canjea el código en https://amautix.com/agent-auth/token. Solicita únicamente amautix:help:read (openid es opcional para el identificador seudónimo). Usa access tokens opacos de hasta cinco minutos en Authorization: Bearer; nunca en la URL. El recurso comprueba issuer, audience, exp, iat, scope e introspección en cada solicitud; los tokens se almacenan cifrados y la revocación es inmediata. Revoca el token en https://amautix.com/agent-auth/revoke con la autenticación del cliente correspondiente, o solicita al operador que retire el cliente y reinicie el servicio. No se emiten refresh tokens. Los clientes de máquina requieren credenciales confidenciales entregadas por el operador y usan client_credentials para el mismo permiso de ayuda. Tokens inválidos: 401; scopes insuficientes: 403. La credencial no da acceso a cuentas, estudiantes ni evaluaciones.

## Registro y revocación

Esta instancia implementa el perfil experimental Auth.md fijado al commit 5081610cb626a40f6462da558a45f37ca245bd3b (no es un estándar IETF). Descubre agent_auth en /.well-known/oauth-authorization-server. Solo acepta type=anonymous con admisión previa del operador, sin registro anónimo abierto, ID-JAG ni service_auth. El operador entrega por un canal privado un ticket de un uso y cinco minutos, vinculado al nombre verificado. No lo publiques ni lo incluyas en URLs.

1. POST https://amautix.com/agent-auth/identity con Content-Type: application/json, Authorization: Bearer <ticket privado> y cuerpo {"type":"anonymous"}. Guarda en memoria client_id, identity_assertion y claim_token de la respuesta. El registro dura una hora y hay un máximo de 100 vigentes.
2. POST https://amautix.com/agent-auth/token con application/x-www-form-urlencoded: grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer, client_id=<client_id>, assertion=<identity_assertion>, resource=https://amautix.com/agent-api/authorized-help. Solo se emite amautix:help:read; el token es opaco y dura como máximo 300 segundos. La aserción puede reutilizarse hasta 15 minutos, salvo revocación o vinculación posterior. No hay refresh_token.
3. Opcionalmente, pide al usuario vincularlo a su cuenta: POST https://amautix.com/agent-auth/identity/claim con JSON {"claim_token":"<valor privado>","email":"<correo del usuario que autoriza>"}. Comparte solo con ese usuario verification_uri y user_code. Debe iniciar sesión como profesor, padre o administrador, comprobar el nombre del agente y escribir el código. El correo se compara mediante HMAC; no se declara verificado ni se entrega en tokens. El código vence en diez minutos, admite cinco fallos y el registro permite cuatro intentos de vinculación.
4. Consulta https://amautix.com/agent-auth/token cada cinco segundos con grant_type=urn:workos:agent-auth:grant-type:claim, client_id y claim_token. Respeta authorization_pending, slow_down y expired_token. Al aprobar, recibe token y una nueva identity_assertion; desecha la anterior y todos sus tokens, que quedan revocados. Pre y posvinculación conservan el mismo permiso de ayuda pública.

Revoca un token en https://amautix.com/agent-auth/revoke, incluyendo client_id y token. Revoca todo el registro con POST https://amautix.com/agent-auth/identity/revoke y Authorization: Bearer <identity_assertion vigente>; responde 204 sin cuerpo. La persona puede revocar sus registros vinculados en https://amautix.com/agent-auth/agents con su sesión, confirmación y CSRF. register_uri es un alias de identity_endpoint y claim_uri de claim_endpoint: mismos endpoints, admisión y contrato. anonymous.credential_types_supported anuncia access_token obtenido en el canje OAuth del paso 2; el registro no entrega directamente esa credencial. No implica soporte de otros flujos de registro antiguos. No existe receptor de eventos externos. Las cuentas de alumnos no pueden vincular agentes.

[Documentación de integración](https://amautix.com/developers) · [Privacidad](https://amautix.com/privacidad)
