Conceptos básicos
Permisos
Un rechazo tiene tres causas distintas: la clave no tiene un scope, el propietario de la clave no tiene un permiso, o la cuenta no tiene un add-on. Cada una tiene un estado o código distinto y una solución distinta.
Tres tipos de rechazo
Enlace a esta sección: Tres tipos de rechazo| Estado y código | Trata de | Cómo solucionarlo |
|---|---|---|
403 insufficient_scope | La clave. No incluye el scope que exige la operación, nombrado en requiredScope. | Vuelve a emitir la clave con ese permiso (scope). |
403 forbidden | El propietario de la clave. La clave es correcta, pero su propietario carece del módulo, la organización o el permiso de administrador que exige la operación. | Lo concede un administrador de la cuenta. |
402 addon_required | El add-on. La cuenta no ha contratado, o ha dejado caducar, el add-on de ese módulo, y requiredAddon lo nombra. Ningún rol lo evita. La API y el MCP no son un add-on. | Añade el add-on a la suscripción. Consulta Planes y add-ons. |
Distinguirlos importa: enviar los tres al mismo sitio te manda a depurar en el lugar equivocado dos de cada tres veces.
Permisos (scopes)
Enlace a esta sección: Permisos (scopes)Una clave lleva scopes que limitan qué operaciones puede llamar, como orders:read y orders:write. Hay 59 en total, listados con lo que abre cada uno en Permisos (scopes). Concede lo mínimo que necesita una clave. Dos merecen cuidado: workflows:run puede modificar datos de forma indirecta porque el workflow hace lo que digan sus pasos, y ai:ask gasta crédito de IA de la cuenta. El centro de ayuda explica las mismas decisiones en Scopes y permisos de la API.
La persona detrás de la clave
Enlace a esta sección: La persona detrás de la claveUna clave depende de un administrador de la cuenta, y el actor de todo lo que escribe es ese administrador, el propietario de la clave. Si la cuenta tiene el registro de actividad, que es un add-on, marca estos cambios como procedentes de la API (y de MCP, para los asistentes), de modo que se puedan distinguir de los cambios hechos en la app. Esa condición se comprueba en cada petición, no solo cuando se crea la clave. Consulta De quién es la clave para el resto.
| Qué ha cambiado | Respuesta |
|---|---|
| La persona que creó la clave dejó la cuenta o fue desactivada | 401 api_key_owner_inactive |
| La persona ya no es administradora | 401 api_key_owner_not_admin |
Si tu integración recibe de repente uno de estos, la clave está bien y lo que ha cambiado es el rol de su propietario. Vuelve a emitir la clave desde una cuenta que siga siendo administradora. Prevé este caso: usa una clave cuyo propietario sea poco probable que se marche y vigila estos códigos. Los roles dentro de la app se describen en Roles y permisos.
Páginas relacionadas
Enlace a esta sección: Páginas relacionadasGuías
Autenticación
Cada operación requiere una clave de API enviada como bearer token. Solo un administrador puede crear una clave, y la clave actúa como ese administrador, así que decide quién la posee antes de crearla.
Guías
Permisos (scopes)
Una clave lleva permisos; cada operación exige exactamente uno. Concede los mínimos que necesites.
Conceptos básicos
Planes y add-ons
La API y el MCP están incluidos en cualquier plan de pago; no son un add-on. El acceso necesita un administrador y que Filmo haya activado la API para tu entorno; algunos módulos necesitan su add-on. Llama a
GET /apipara ver qué add-ons tiene hoy la cuenta./v1 /account
¿Te ha resultado útil esta página?