Permisos de la API (scopes)

Qué puede leer o cambiar una clave de API o un asistente de IA conectado, cómo elegir sus permisos y qué hacer cuando se rechaza una llamada.

Administradores de la cuenta: los roles «Superadministrador», «Administrador» y «Propietario». El resto de personas no ven «API y MCP» en Configuración.

Los permisos, que la API llama scopes, dicen qué puede hacer una clave de API o un asistente de IA conectado. Se eligen al crear la clave o al conectar el asistente, y son lo primero que hay que mirar cuando se rechaza una llamada.

Cómo se llaman los permisos

La mayoría se escribe como un área y una acción, por ejemplo orders:read. Hay uno por cada área y acción, y la lista completa está en la guía para desarrolladores de abajo.

…:read permite a la clave consultar esa área. Nunca cambia nada.
…:write le permite crear o cambiar cosas en esa área y, en algunas áreas, también borrarlas. Lee la descripción de cada uno antes de darlo.
Dos excepciones: ai:ask permite preguntar a la IA de Filmo sobre tus datos, y workflows:run permite ejecutar tus workflows.

Permiso	Qué permite
`account:read`	Ver los ajustes básicos de la cuenta (nombre, zona horaria, moneda, módulos) y los datos de la propia clave
`orders:read`	Ver todos los pedidos de la cuenta, con sus importes
`orders:write`	Crear pedidos, modificar su cabecera, reservarlos y desreservarlos, cancelarlos, archivarlos y registrar devoluciones
`contacts:read`	Ver todos los contactos, con su correo y su teléfono
`contacts:write`	Crear, modificar y borrar contactos y sus direcciones. Borrar no se puede deshacer y elimina también las notas, los archivos y las tareas del contacto; se rechaza si el contacto tiene pedidos o facturas
`items:read`	Ver todo el catálogo de artículos
`tasks:write`	Crear, modificar y borrar tareas. Borrar no se puede deshacer
`availability:read`	Consultar qué artículos están libres y las bajas declaradas de personal, vehículos y espacios
`ai:ask`	Preguntar a la IA de Filmo sobre los datos de la cuenta (gasta créditos de IA)
`workflows:run`	Ejecutar los workflows de la cuenta que tienen disparador manual y una versión guardada. Lo que haga un workflow depende de sus pasos

Los permisos de escritura pueden más que crear y modificar

Algunos también borran y otros tocan dinero. Por ejemplo, contacts:write y tasks:write pueden borrar, y un borrado no se puede deshacer. invoices:write valida y anula facturas, abonos y proformas, y además puede registrar o actualizar la copia de una factura emitida por otro sistema, con sus importes. quotes:write mueve el estado comercial de un presupuesto pero no puede crearlo. Las descripciones completas están en la pantalla donde los marcas.

Dónde se eligen

Al crear una clave de API

Los permisos salen en dos bloques: los de consulta («Consulta») y los que modifican datos («Permisos que modifican datos»), destacado, donde también está workflows:run. Ninguno viene marcado, y cada bloque tiene un botón para marcar o desmarcar todo. Úsalo con cuidado: una clave con todo marcado puede hacer mucho más de lo que casi cualquier herramienta necesita.

Al conectar un asistente de IA

En la pantalla donde apruebas el asistente, solo vienen marcados los permisos de consulta. Los permisos que cambian datos, workflows:run y ai:ask salen siempre sin marcar, aunque el asistente los pida; los que ha pedido llevan la etiqueta «Lo pide la integración». Tú marcas los que aceptas. La pantalla también muestra la dirección a la que se enviarán los datos, y te avisa si el asistente solo puede responder a tu propio ordenador.

Qué permisos dar

Quieres…	Dale
Mostrar tus pedidos en un informe o un panel	`account:read`, `orders:read` y los demás permisos `:read` que use el informe
Enviar a Filmo las solicitudes del formulario de tu web	`account:read`, `contacts:read`, `contacts:write`. Ten en cuenta que `contacts:write` también puede borrar contactos; usa una clave hecha solo para el formulario
Que un asistente de IA responda preguntas	Los permisos `:read` de las áreas que deba ver. Añade un permiso `:write` solo para lo que quieras que cambie
Ejecutar un workflow desde otra herramienta	`workflows:read` y `workflows:run`

Empieza con poco

Da a una clave los permisos mínimos con los que la herramienta funcione. Si se rechaza una llamada puedes crear una clave nueva con un permiso más; lo que una clave ya hizo no se puede deshacer.

Algunas llamadas necesitan además un módulo de tu plan

En algunas áreas un permiso no basta. Los módulos de CRM, de gestión de incidencias y reparaciones, de compras y de campos personalizados, y los créditos de IA para ai:ask, tienen que formar parte de tu plan. Sin ellos la llamada se rechaza con un mensaje de que el plan no incluye el add-on.

Cuando se rechaza algo

Qué indica la herramienta	De quién es el límite	Cómo arreglarlo
La clave no tiene el scope requerido (403)	La clave	Crea una clave nueva con ese permiso. En un asistente, quita el conector y vuelve a añadirlo aprobando el permiso extra
No tienes permiso para ejecutar esta operación (403)	El administrador que creó la clave: le falta el módulo, o la operación es solo para administradores	Da a esa persona acceso al módulo o el rol de administrador, o usa otro administrador
El usuario que creó la clave ya no está activo, o ya no es administrador (401)	El propietario de la clave	Crea una clave nueva desde una cuenta que sea administradora
Tu plan no incluye el add-on que requiere esta operación (402)	Tu plan	Añade el módulo a tu plan

Quien desarrolla encontrará cada permiso, con las operaciones que abre, en la guía de scopes, y los permisos que convienen a cada tipo de asistente de IA en la guía de límites de MCP.

Recursos relacionados

Crea una clave y elige sus permisos: Genera una clave de API.
Quién puede hacer qué en la aplicación: Roles y permisos.
Conecta un asistente: Conecta un asistente de IA.

Preguntas frecuentes

¿Sigues atascado? Contacta con soporte