Autenticación
OAuth 2.1 con PKCE y registro dinámico de clientes, tokens acotados a una organización, roles, scopes, duración y revocación.
El servidor MCP de Vidext Operator se autentica con OAuth 2.1: código de autorización con PKCE, más registro dinámico de clientes. No hay API keys de larga duración. Los clientes se registran solos, una persona autoriza en el navegador y los tokens duran poco y quedan ligados a una organización.
El emisor OAuth es:
https://app.vidext.com/api/authEl flujo (lo que tu cliente hace por ti)
Challenge
La primera petición sin un token válido recibe HTTP 401 con un challenge WWW-Authenticate: Bearer. Su resource_metadata apunta al documento de recurso protegido de este endpoint, /.well-known/oauth-protected-resource/api/mcp/operator.
Descubrimiento
El documento de recurso protegido nombra el servidor de autorización. Sus metadatos son un único documento servido en varias rutas (consulta la tabla de abajo), así que un cliente que parte del emisor y otro que lee la ruta raíz obtienen la misma respuesta.
Registro
Un cliente sin credenciales se registra solo en /api/auth/oauth2/register. El registro no necesita una cuenta previa. Un cliente puede usar en su lugar como client_id una URL HTTPS que sirva su documento de metadatos de cliente.
Autorización
El navegador abre /api/auth/oauth2/authorize. La persona inicia sesión, revisa la pantalla de consentimiento y, si es admin o miembro en más de una organización, elige una. La elección queda ligada a esta autorización.
Tokens
El cliente intercambia el código y su verificador PKCE en /api/auth/oauth2/token. Los tokens renovados conservan la misma organización.
Referencia de endpoints
| Endpoint | Ruta |
|---|---|
| Metadatos del servidor de autorización | /.well-known/oauth-authorization-server, también en /.well-known/oauth-authorization-server/api/auth (derivada del emisor, RFC 8414) y /api/auth/.well-known/oauth-authorization-server |
| Configuración OpenID | /.well-known/openid-configuration, también en /.well-known/openid-configuration/api/auth y /api/auth/.well-known/openid-configuration |
| Metadatos del recurso protegido | /.well-known/oauth-protected-resource/api/mcp/operator (el que nombra el challenge) y /.well-known/oauth-protected-resource |
| Registro dinámico de clientes | /api/auth/oauth2/register |
| Autorización | /api/auth/oauth2/authorize |
| Token | /api/auth/oauth2/token |
| Revocación | /api/auth/oauth2/revoke |
| Información del usuario | /api/auth/oauth2/userinfo |
| JWKS (emisor OAuth) | /api/auth/jwks |
Existen dos endpoints JWKS
/api/auth/jwks es el juego de claves del emisor OAuth. El /.well-known/jwks.json aparte sirve a la integración con el LMS (LTI). No los confundas.
Quién puede conectarse
Solo los admins y miembros de la organización pueden usar el servidor.
- En la autorización, el selector de organización solo lista las organizaciones donde la persona es admin o miembro. Quien no tiene ninguno de esos roles en ninguna organización recibe un
403. - En cada llamada a una tool, el servidor vuelve a comprobar el rol. A una persona a la que se elimina de la organización, o cuyo rol pasa a participante, su siguiente llamada le devuelve el error de tool
forbidden, y su siguiente renovación de token se rechaza. - Los participantes y los solicitantes (personas cuya solicitud para unirse sigue pendiente) no pueden conectarse.
Admins y miembros ven los mismos datos por MCP: todos los módulos de la organización y las fuentes procesadas de la organización. No hay filtrado por equipo para estos dos roles. Consulta roles y permisos.
Ámbito de organización
Un token está ligado a una persona en una organización, fijada en la autorización. Sigue ligado aunque la persona cambie después de espacio de trabajo en la aplicación. Para trabajar en otra organización, vuelve a autorizar.
Cada tool acepta los argumentos opcionales organizationSlug y organizationId. Si los omites, la llamada usa la organización del token. Pasar otra organización se rechaza con organization_scope_mismatch; pasar un id y un slug que nombran organizaciones distintas se rechaza con invalid_organization_selector.
Scopes
| Scope | Qué concede |
|---|---|
mcp:operator.read | Todas las tools que expone el servidor. Todas son lecturas. Pide este. |
mcp:operator.write | Se acepta por compatibilidad. Concede las mismas tools de lectura; ninguna tool lo necesita. |
Un token sin ninguno de los dos se rechaza con 403 e insufficient_scope. El servidor admite además los scopes estándar openid, profile, email y offline_access para el inicio de sesión y la renovación.
Tokens
- Los tokens de acceso son JWT firmados (
typ: at+jwt) que duran una hora. Su audiencia es la URL del endpoint MCP, así que un token emitido para un origen no se acepta en otro. - Los tokens de renovación duran 30 días. Cada renovación emite un par nuevo ligado a la misma organización, tras comprobar que la persona sigue siendo admin o miembro ahí.
- No se aceptan tokens con restricción de emisor (DPoP).
- Las cookies de sesión de la aplicación web no se aceptan como tokens bearer. Solo el flujo OAuth, o el camino headless de abajo, emite un token válido.
Revocación
- Desde tu cliente. Elimina la conexión en tu cliente de IA. Un cliente también puede revocar su token de renovación en
/api/auth/oauth2/revoke, lo que impide más renovaciones. - Desde Vidext. Hoy no hay un control de "desconectar" en la configuración de Vidext. Eliminar a la persona de la organización, o cambiar su rol a participante, detiene sus llamadas a tools desde la siguiente llamada y bloquea la siguiente renovación.
- Un token de acceso ya emitido sigue siendo válido criptográficamente hasta que caduca (como mucho una hora), pero cada llamada vuelve a comprobar el rol de la persona.
Cuando un token caduca o se rechaza, el servidor vuelve a responder 401 y los clientes bien hechos repiten el flujo.
Agentes headless
Para un agente sin navegador, /auth.md describe un registro con email verificado en nombre de un usuario de Vidext existente:
POST /api/agent/authcon el email del usuario. Vidext le envía un código de seis dígitos, válido 10 minutos, y devuelve un claim token.POST /api/agent/auth/claim/completecon el claim token y el código (cinco intentos). Si el usuario está en más de una organización, la respuesta pide al agente que reintente con unorganization_id.- La respuesta lleva un token de acceso válido 7 días, con los dos scopes de operator. No hay token de renovación: cuando caduca o una llamada devuelve
401, vuelve a registrarte.
Los dos endpoints POST aceptan una cabecera Idempotency-Key (se guarda 24 horas) y tienen límite de tasa por IP: 60 registros y 30 completados por hora. En cada llamada a una tool se aplica la misma regla de roles. OAuth interactivo es el camino recomendado; este existe para agentes que no pueden abrir un navegador.
Last updated on