Autenticación y permisos

Ambos acaban siendo lo mismo: el token de acceso de una conexión OAuth es una clave de Filmo (fk_live_…), así que también funciona en la API REST. Autenticación REST trata las claves; una suscripción puede tener hasta 50 claves no revocadas, contando las claves caducadas y las conexiones OAuth; el límite te impide crear otra clave a mano.

Una llamada sin credencial a https://app.filmo.io/api/v1/mcp recibe un HTTP 401 con un cuerpo de problema y una cabecera WWW-Authenticate: Bearer realm="filmo-public-api", resource_metadata="…", scope="<the read scopes>". El cliente lee los metadatos del recurso protegido (RFC 9728) en https://app.filmo.io/.well-known/oauth-protected-resource y los metadatos del servidor de autorización (RFC 8414) en https://app.filmo.io/.well-known/oauth-authorization-server. Los metadatos nombran https://app.filmo.io como emisor y https://app.filmo.io/api/v1/mcp como recurso, y su resource_documentation apunta a esta página.

• El scope del 401 lista los permisos de lectura, así que los clientes que lo usan piden lectura por defecto.
• scopes_supported enumera todos los permisos (scopes), incluidos los de escritura.
• Se exige PKCE S256; plain se rechaza. La única autenticación de cliente es ninguna (clientes públicos).
• Cualquier otro host de producción responde con una redirección (308) al canónico y, para un cliente que no la sigue en un POST, con un error JSON-RPC que nombra la URL. Un cliente que la sigue descarta la cabecera Authorization cuando cambia el origen.
• No anunciados: client ID metadata documents, iss en la respuesta de autorización, offline_access y un endpoint de revocación. El parámetro resource se ignora: el token no tiene audiencia.

Los clientes se registran por sí mismos (RFC 7591) en https://app.filmo.io/api/v1/oauth/register. El registro es abierto y no necesita credencial, con hasta 10 URI de redirección por cliente; se aceptan las https, las de loopback (http en 127.0.0.1, localhost o [::1], con cualquier puerto) y el esquema personalizado de una app nativa (como myapp://callback); nunca se acepta un fragmento, y la URI de redirección de una petición tiene que coincidir exactamente con una de ellas. Está limitado a 5 registros por minuto y dirección.

Solo un administrador de la cuenta de Filmo puede dar el consentimiento, y elige la suscripción a la que queda ligada la conexión. La pantalla ofrece todos los scopes y marca por defecto solo el mínimo:

• Se comprueban los permisos (scope) *:read que pidió el cliente; si no pidió ninguno, se comprueban todos los permisos de lectura.
• Las escrituras, workflows:run y ai:ask empiezan sin marcar aunque el cliente los pida. Lo que pidió lleva “Requested by the integration”; lo que no pidió, “Not requested by the integration”.
• scope es opcional en la petición y los permisos (scopes) que Filmo no conoce (openid, offline_access, una errata) se ignoran.
• La pantalla muestra el host de redirección y avisa cuando todas las redirecciones del cliente son loopback. No avisa de un esquema propio de la app.
• Puedes conceder un permiso que el cliente no pidió. La respuesta del token devuelve el scope realmente concedido, que puede ser menor que el solicitado.

Cualquiera puede registrar un cliente con cualquier nombre, porque el registro es abierto y se aceptan redirecciones a loopback en cualquier puerto. Por eso una página web o un proceso de tu ordenador puede pedir consentimiento como «Claude» o como cualquier otro producto. Antes de aprobar:

• Comprueba el host de redirección que muestra la pantalla con la página del cliente en Conectar: claude.ai para Claude, chatgpt.com para ChatGPT.
• Desconfía de un cliente que solo redirige a tu propio ordenador, a menos que lo hayas iniciado tú mismo, desde una herramienta que instalaste.
• Una redirección que no es https no tiene un host que comprobar. Un esquema de aplicación personalizado (myapp://…) abre una aplicación instalada en este ordenador o teléfono; apruébalo solo si iniciaste el inicio de sesión desde esa aplicación.
• No apruebes nunca un consentimiento que no hayas iniciado.
• Revisa cada scope. Una escritura que no necesitas es una escritura que puede usar una instrucción inyectada.

• El código de autorización dura 60 segundos y sirve una sola vez.
• El token de acceso dura 1 hora. El token de refresco dura 30 días y se rota en cada intercambio: el token de acceso anterior deja de funcionar al instante.
• Un refresh token usado dos veces en 10 segundos por el mismo cliente devuelve el mismo par; si se usa de nuevo más tarde, se revoca toda la cadena y el cliente debe pedir consentimiento otra vez.
• Los errores de OAuth son { error, error_description }, no documentos de problema, y la descripción está en español. En un 429 sigue Retry-After, no el cuerpo.

Una herramienta para la que la conexión no tiene permiso (scope) devuelve insufficient_scope como error de herramienta con requiredScope; no hay petición para ampliar permisos. Para añadir un permiso, elimina el conector y vuelve a añadirlo.

Revoca una conexión o una clave en la página API y MCP de los ajustes de la aplicación. El token de acceso falla con api_key_revoked al instante, y el token de refresco ya no se puede canjear.