Autenticación

Pon la clave en la cabecera Authorization de cada petición, como token bearer. Toda clave empieza por fk_live_: hay un único prefijo y no existen claves de prueba ni de sandbox, así que toda clave funciona sobre los datos reales de su cuenta. La documentación es pública; lo restringido es la credencial.

GET /api/v1/account HTTP/1.1
Host: app.filmo.io
Authorization: Bearer <your API key>

Para comprobar qué puede hacer una clave, llama a GET /api/v1/account. Devuelve la clave que hizo la petición, con su nombre y sus permisos, pero nunca su secreto (apiKey).

# The scopes of the key are in data.apiKey.scopes.
curl -sS "${FILMO_BASE_URL:-https://app.filmo.io}/api/v1/account" \
  -H "Authorization: Bearer $FILMO_API_KEY" | jq '.data.apiKey'

const base = process.env.FILMO_BASE_URL ?? "https://app.filmo.io";
const res = await fetch(base + "/api/v1/account", {
  headers: { Authorization: `Bearer ${process.env.FILMO_API_KEY}` },
});
if (!res.ok) {
  // 401 and 403 come back as application/problem+json: branch on `code`.
  const problem = await res.json();
  throw new Error(res.status + " " + problem.code + " (request " + problem.requestId + ")");
}
const { data } = await res.json();
console.log(data.apiKey.name, data.apiKey.scopes);

import os
import requests

base = os.environ.get("FILMO_BASE_URL", "https://app.filmo.io")
res = requests.get(
    base + "/api/v1/account",
    headers={"Authorization": f"Bearer {os.environ['FILMO_API_KEY']}"},
    timeout=30,
)
if not res.ok:
    # 401 and 403 come back as application/problem+json: branch on "code".
    problem = res.json()
    raise SystemExit(f"{res.status_code} {problem['code']} (request {problem['requestId']})")
key = res.json()["data"]["apiKey"]
print(key["name"], key["scopes"])

1. 1

   Iniciar sesión como administrador

   Solo los administradores de la cuenta pueden crear claves, a mano o mediante OAuth.

2. 2

   Abrir los ajustes de API y MCP

   En la interfaz en español, la sección se llama Ajustes → API y MCP.

3. 3

   Crea la clave y ponle el nombre de la integración

   Usa una clave por integración, para poder revocar una sin tocar las demás.

4. 4

   Elegir los scopes

   Marca solo los permisos que la integración llama. Los scopes de una clave no se pueden editar después: para cambiarlos, crea una clave nueva y revoca la antigua. Consulta Permisos (scopes).

5. 5

   Establecer una fecha de caducidad, si quieres una

   La fecha es opcional y debe ser futura. Una clave sin fecha no caduca, y ninguna clave caduca por falta de uso.

6. 6

   Copia la clave y guárdala

   Filmo muestra la clave una sola vez y guarda solo un hash de ella, así que no puede volver a mostrarla. Guárdala en un gestor de secretos o en una variable de entorno antes de cerrar el diálogo.

El centro de ayuda tiene el mismo procedimiento con pantallas: Generar una clave de API.

Una clave depende de un administrador real de la cuenta, el que la creó, y todo lo que escribe se atribuye a ese administrador. Lo mismo vale para cada conexión OAuth.

Filmo comprueba esa condición en cada petición, no solo cuando se crea la clave. Si la persona que creó la clave deja la cuenta o se desactiva, la clave responde 401 api_key_owner_inactive. Si deja de ser administradora, responde 401 api_key_owner_not_admin. La clave en sí está bien: lo que cambió es el rol de su propietario, y la solución es volver a emitir la clave desde una cuenta que siga siendo administradora.

No crees claves de producción desde la cuenta de una persona que pueda marcharse o cambiar de rol. Crea una cuenta de administrador dedicada y duradera para las integraciones, ponle un nombre que diga para qué sirve y crea las claves desde ella. Hoy no existe un usuario de servicio ni de bot: el propietario de la clave es un usuario real. La clave en sí no ocupa una plaza, pero la cuenta de administrador desde la que la creas es un usuario como cualquier otro y sí la ocupa, así que cuenta con esa cuenta en tu presupuesto.

Un desarrollador o una agencia que trabaja para una empresa de alquiler no es administrador de su cuenta y no puede crear una clave. El administrador de la empresa de alquiler crea la clave solo con los scopes que necesita el trabajo y la entrega mediante un gestor de secretos compartido, nunca por correo ni por chat. El contratista no necesita un acceso de administrador. Cuando termina el trabajo, el administrador revoca la clave.

Revoca una clave en la sección API y MCP de los ajustes (*Ajustes → API y MCP*). Una clave revocada responde 401 api_key_revoked. Una conexión hecha mediante OAuth aparece ahí etiquetada como integración conectada, y revocarla corta el acceso de inmediato.

No hay un comando de rotación. Pueden estar activas varias claves a la vez, y ese solapamiento es la forma de rotar una clave sin tiempo de inactividad:

1. 1

   Crear una clave nueva

   Mismo patrón de nombre y mismos scopes.

2. 2

   Desplegarla

   Actualiza el secreto que lee tu integración y reinicia la integración.

3. 3

   Revisar el tráfico

   Confirma que las llamadas de la integración funcionan con la nueva clave.

4. 4

   Revoca la clave antigua

Una suscripción puede tener hasta 50 claves sin revocar (una clave caducada sigue contando). Las conexiones OAuth cuentan en ese total, pero solo se rechaza al llegar al límite la creación de una clave a mano. Revoca las que ya no uses.

Una petición sin una clave utilizable se responde con 401 y un documento de problema. Ramifica según code. Filmo comprueba una clave en este orden: se reconoce, luego no está revocada, luego no ha caducado, luego su propietario sigue siendo un administrador activo; la primera comprobación que falla decide el código. Un 401 y un 403 insufficient_scope no consumen cuota del límite de peticiones; toda otra respuesta de una clave autenticada sí.

Un 403 es un problema distinto: la clave se autenticó, pero no puede hacer esto. insufficient_scope se refiere a la clave, forbidden a su propietario y addon_required (402) al add-on de un módulo. Errores los distingue. Todo cuerpo de error lleva un requestId; cítalo cuando contactes con soporte.

• Llama a la API desde un servidor. No pongas nunca una clave en código de navegador, en una app móvil ni en un repositorio público: quien la tenga tiene acceso programático a los datos de la empresa. En producción la API acepta peticiones de navegador de otro origen solo desde https://docs.filmo.io, y los endpoints de OAuth y MCP no envían ninguna cabecera CORS, así que una página de cualquier otro origen no puede llamarla de todos modos.
• Lee la clave de una variable de entorno o de un gestor de secretos, como hacen los ejemplos con FILMO_API_KEY.
• No escribas la cabecera Authorization en los registros.
• Da a cada integración su propia clave, con los scopes más estrictos que necesite.
• Configura alertas para 401 api_key_owner_inactive y api_key_owner_not_admin: significan que una integración está a punto de dejar de funcionar. Consulta Pasar a producción.

Cada clave lleva un conjunto de permisos (scopes), elegidos cuando un administrador la crea en la sección de API y MCP de los ajustes (*Ajustes → API y MCP*). Cada operación exige exactamente un permiso (scope), que se muestra en su página y en el archivo OpenAPI como x-required-scope. En total hay 59 permisos (scopes).

• orders:read permite a una clave leer pedidos. orders:write le permite crearlos, modificarlos y actuar sobre ellos. No des por hecho que escribir incluye leer: una clave que escribe pedidos y los vuelve a leer necesita ambos.
• Un permiso (scope) cubre un recurso, no una sola operación. Un permiso (scope) de escritura cubre todas las creaciones, actualizaciones, eliminaciones y acciones sobre ese recurso.
• Algunos scopes no tienen gemelo de escritura, como account:read, users:read y schedule:read.
• Dos permisos son especiales. workflows:run ejecuta un workflow. ai:ask pregunta a la IA sobre tus datos y gasta créditos de IA.

Los permisos (scopes) acotan qué operaciones puede llamar una clave. Los datos que ve se acotan aparte por la cuenta (consulta Cuentas y aislamiento), y algunas operaciones necesitan además un add-on en la cuenta. Por MCP rigen los mismos scopes, y una clave solo ve las herramientas que puede llamar.

Una clave sin el scope que necesita una operación recibe 403 insufficient_scope. El cuerpo nombra el scope que falta en requiredScope. Se arregla emitiendo una clave que tenga ese scope.

{
  "type": "https://docs.filmo.io/errors/insufficient_scope",
  "title": "Insufficient scope",
  "status": 403,
  "code": "insufficient_scope",
  "detail": "The API key does not have the required scope (orders:write)",
  "requiredScope": "orders:write",
  "requestId": "req_5f1c2f4e3a5b4f6d8e7a0b1c2d3e4f5a"
}

Otras dos denegaciones se parecen y tienen soluciones distintas.

El centro de ayuda explica los permisos en la app: Scopes y permisos de la API y Roles y permisos.

• Una clave por integración, para poder revocar una sin tocar las demás.
• Empieza con los scopes :read. Añade un scope de escritura solo para el recurso en el que escribes.
• Incluye siempre account:read. GET /api/v1/account es la primera llamada de cualquier integración: devuelve los permisos (scope) de la clave, los add-ons de la cuenta y la versión del contrato.
• Deja fuera ai:ask y workflows:run salvo que la integración los use de verdad.
• Comprueba qué puede hacer realmente una clave llamando a GET /api/v1/account con ella. Una clave creada mediante OAuth puede acabar con scopes distintos de los solicitados (menos, o adicionales que ha marcado el administrador).

curl -sS "${FILMO_BASE_URL:-https://app.filmo.io}/api/v1/account" \
  -H "Authorization: Bearer $FILMO_API_KEY"

Son puntos de partida. Quita lo que tu integración no use; añade lo que una llamada concreta pida en requiredScope.

• account:read
• contacts:read
• contacts:write
• Opcional: custom-fields:read para mapear los campos personalizados, y tags:read y tags:write para etiquetar lo que importes.

• account:read
• contacts:read para buscar a la persona
• contacts:write para crearla
• crm:read para leer los embudos
• crm:write para crear la oportunidad
• Las operaciones de CRM también necesitan el add-on de CRM en la cuenta.

• account:read
• availability:read
• items:read
• contacts:read y contacts:write
• orders:read y orders:write para crear y reservar el pedido

• account:read
• items:read, que también cubre las unidades serializadas
• Opcional: spaces:read para los almacenes y items:write solo si escribes de vuelta datos de stock

• account:read
• schedule:read
• Opcional: tasks:read, planner:read, staff:read y vehicles:read si también necesitas tareas, recursos asignables, personal o vehículos

• account:read
• invoices:read, que cubre las facturas, sus líneas y las notas de crédito
• treasury:read para los pagos
• contacts:read para el identificador fiscal del cliente
• invoices:write solo si reflejas las facturas emitidas por tu ERP con PUT /api/v1/invoices/external/{originSystem}/{originExternalId}

Cada permiso (scope), con las operaciones que lo necesitan, está en la página de scopes.