API de OAuth

Punto de token OAuth 2.0 (RFC 6749 §3.2) para JWTs de agentes. grant_type refresh_token rota una credencial opaca de actualización (RFC 9700): cada uso devuelve un nuevo par; un request_id (16 a 200 caracteres) hace que un reintento exacto devuelva la misma respuesta mientras su credencial y concesión estén vigentes y el sucesor aún sea actual, sin un plazo de reintento por tiempo transcurrido.

Cualquier otro uso de un token de actualización reemplazado revoca toda la familia (invalid_grant). Una membresía o proyecto seleccionado eliminado devuelve invalid_scope con error_description que comienza con "project_selection_inactive:"; la credencial de actualización no se consume.

Descubra membresías activas con GET /api/projects, crúcelas con la selección previamente consentida y reintente con projects= y un nuevo request_id. Nunca termine la familia de actualizaciones por este error de selección.

La restricción del ámbito solicitado se aplica independientemente a cada proyecto y a la autoridad de identidad; un ámbito explícito sin identidad excluye la autoridad de identidad. grant_type urn:ietf:params:oauth:grant-type:token-exchange (RFC 8693) con subject_token_type urn:screenrig:token-type:identity-credential o urn:screenrig:token-type:project-token responde unsupported_token_type: las credenciales heredadas están retiradas, y la instalación inicia sesión de nuevo con screenrig login. resource (RFC 8707) es https://api.<domain>/api o está ausente; projects selecciona hasta 64 IDs de proyectos consentidos.

La omisión selecciona todo solo cuando el conjunto cabe; de lo contrario el cliente debe elegir un subconjunto. project_id selecciona uno durante la versión de compatibilidad. La concesión de una app conectada tiene el único recurso https://api.<domain>/mcp, que una actualización puede omitir.

Los clientes son públicos (solo client_id), o una app conectada cuyo metadata declara que private_key_jwt se autentica con client_assertion_type urn:ietf:params:oauth:client-assertion-type:jwt-bearer y un client_assertion (iss y sub son su client_id, aud el emisor o este endpoint como una cadena, exp dentro de 5 minutos de iat, un jti usado una vez, kid nombrando una de sus claves; EdDSA, ES256 o RS256). grant_type authorization_code canjea el código de una app conectada en 60 segundos con el redirect_uri exacto y el PKCE code_verifier; resource debe estar ausente o ser el autorizado; un segundo canje revoca el permiso creado por el código. grant_type client_credentials es de un cliente de servicio: se autentica con una afirmación de cliente (una de sus claves registradas) o su secreto por HTTP Basic (client_secret_basic; un secreto en el cuerpo es rechazado) y recibe un token de servicio de 15 minutos para su proyecto, audiencia api o (resource https://api.<domain>/mcp) mcp, scope dentro de sus capacidades y nivel de acceso, y sin token de actualización; 600 por cliente por hora.

Los errores son JSON {error, error_description} según RFC 6749 con Cache-Control no-store; mientras el servidor no lo emite responde temporarily_unavailable (503).

Los límites de frecuencia responden 429 rate_limited con Retry-After: 1200 solicitudes por dirección cliente por hora en este y el endpoint de revocación, 60 actualizaciones por concesión por hora, 30 intercambios por credencial heredada por hora. grant_type urn:ietf:params:oauth:grant-type:device_code (RFC 8628 §3.4) consulta un inicio de sesión de dispositivo: authorization_pending hasta que una persona lo apruebe, slow_down si se consulta antes del intervalo (que luego crece 5 segundos), access_denied cuando se niega, expired_token tras 10 minutos, luego la respuesta del token.

Una nueva instalación recibe un par de tokens; un inicio de sesión iniciado con el token de acceso de una instalación existente añade el proyecto aprobado a esa concesión y recibe solo un token de acceso, sin rotar el token de actualización. Consultar el mismo device_code otra vez devuelve la misma respuesta hasta que la concesión rota primero o pasan 10 minutos, luego invalid_grant.

Solo POST, codificado en formulario, sin cadena de consulta.

Autorización de dispositivo RFC 8628 §3.1 para `screenrig login`. scope es access:manage (el predeterminado), access:propose o access:read; project_id sugiere el proyecto que la persona aprueba; name, agent_type, platform y version describen la instalación y se muestran al aprobador según lo reportado por el dispositivo; install_source (opcional) indica desde dónde se instaló y se conserva en el agente que crea la aprobación.

Sin Authorization inicia una nueva instalación. Con Authorization: Bearer y un token de acceso de agente que lleva el alcance de identidad, solicita añadir un proyecto a la concesión de esa instalación, o elevar un proyecto Solo lectura a Administrar.

La persona ingresa user_code en verification_uri (o sigue verification_uri_complete) y lo aprueba en el panel; el dispositivo consulta el endpoint token con device_code cada interval segundos.

Los límites de frecuencia responden 429 rate_limited con Retry-After: 10 por dirección cliente por hora y 600 por hora en toda la flota, detrás de los 1200 por dirección por hora de los endpoints. Los errores son JSON RFC 6749 con Cache-Control no-store; mientras el servidor no emita responde temporarily_unavailable (503). Solo POST, codificado en formulario, sin cadena de consulta.

Punto de autorización OAuth 2.0 para apps conectadas (clientes MCP). client_id es una URL de documento de metadatos de ID de cliente (https, puerto 443, sin redirecciones, máximo 64 KiB y 5 segundos, solo direcciones públicas) o un id de cliente registrado.

La solicitud se valida en este orden: el cliente, el redirect_uri exacto (una redirección http de loopback a 127.0.0.1, [::1] o localhost coincide en cualquier puerto), response_type code, code_challenge con code_challenge_method S256, resource (https://api.<domain>/mcp, otro recurso MCP cuyos metadatos de recurso protegido nombran este servidor, o ausente) y luego scope (access:read, el predeterminado, access:propose, access:manage y nombres de capacidades).

Un cliente desconocido o redirect_uri responde con una página de error HTML y nunca redirige; cualquier error posterior redirige al redirect_uri con error, error_description, state e iss (RFC 9207).

El éxito responde con 303 a la página de consentimiento del panel, donde una persona elige el proyecto, el nivel de acceso (Solo lectura por defecto, Proponer o Administrar) y las capacidades; la aprobación redirige con código, estado e iss. 30 solicitudes por dirección cliente por minuto.

Revocación RFC 7009. Una credencial de actualización opaca (o un JWT de actualización de versión anterior), o un JWT de acceso de agente, emitidos al cliente revocan su concesión; los tokens de acceso de la concesión se rechazan en segundos. Un token desconocido, expirado o extranjero también responde 200. Solo POST, codificado en formulario.

Metadatos del servidor de autorización RFC 8414 para el servidor de autorización del agente.

Metadatos de recurso protegido RFC 9728 para /mcp, nombrados por resource_metadata de cada /mcp 401.

Metadatos de recurso protegido RFC 9728 para /api.

Una autorización pendiente de aplicación conectada para la página de consentimiento: el nombre y dominio del cliente según los declara su metadato (nunca se obtiene un logo), si es un cliente registrado, el host de redirección, y el nivel de acceso y capacidades solicitadas. Las autorizaciones desconocidas, expiradas o resueltas son not_found.

Aprueba una aplicación conectada para uno de los proyectos de la persona tras una prueba reciente (tipo oauth_authorization_approval, sujeto el id de autorización): crea la identidad del agente de la aplicación (tipo agente mcp_client, la persona responsable), su membresía y su concesión con el acceso elegido (leer o administrar; omitido mantiene el nivel solicitado, que por defecto es leer) y capacidades (un subconjunto de lo solicitado), y responde con redirect_uri, que lleva código, estado e iss, a la que la página navega.

El código es válido durante 60 segundos. Un miembro limitado a pantallas no conecta agentes, no emite credenciales ni administra a las personas del proyecto: outside_screen_scope (pida al propietario del proyecto).

Deniega una app conectada tras una prueba reciente (kind oauth_authorization_denial) y responde el redirect_uri, con error=access_denied, state e iss, al que navega la página. Un miembro limitado a pantallas no conecta agentes, no emite credenciales ni administra a las personas del proyecto: outside_screen_scope (pida al propietario del proyecto).