Skip to main content
Las API Keys son por espacio de trabajo. Cada workspace tiene su propia clave y permisos asociados.

​
Obtener tu API Key

  1. Inicia sesión en Agents Studio.
  2. Ve a Ajustes (Settings) del espacio de trabajo actual.
  3. Abre la sección “API Keys”.
  4. Genera una nueva clave o copia una existente.
Sugerencias:
  • Asigna un nombre/nota a cada clave para identificar su uso (p. ej., “Producción - Backend”).
  • Mantén las claves en un gestor seguro de secretos.

​
Alcance y permisos

  • La clave sólo es válida para el workspace donde fue emitida.
  • Acceso restringido a los recursos de ese workspace (chatbots, llamadas, notificaciones, etc.).
  • Puedes revocar o rotar una clave sin afectar otras.

​
Uso en peticiones

Incluye tu clave en el header HTTP como API Key simple (compatible con n8n):
Ejemplo de uso (HTTP):

​
Rotación y buenas prácticas

  • Rotación periódica de claves (al menos trimestral).
  • Revoca claves no utilizadas o comprometidas.
  • Usa claves distintas por entorno (dev/staging/prod).

​
Scopes disponibles

Cada clave debe emitirse con el conjunto mínimo de scopes necesario. La siguiente tabla resume los permisos alineados a la Public API vigente.
GET /v1/workspaces no exige ningún scope: basta una API Key válida. Los scopes de la tabla son los que los guards verifican hoy; pedir uno que no aparezca aquí no otorga ningún permiso adicional, porque nada lo consulta.
Subir un archivo exige dos scopes a la vez, no uno. El carril de /v1/uploads pide uploads:write más el scope de escritura del destino al que va el archivo: una fuente de conocimiento necesita knowledge-bases:write y uploads:write; un documento del brief de un agente, agents:write y uploads:write. Con uno solo, la petición responde 403 nombrando el que falta.Se reutiliza el permiso del recurso consumidor en vez de inventar uno por destino: quien puede escribir un agente puede darle un documento. Lo que no vale es tener el del destino y no el del carril, ni al revés.
Las plantillas de mensaje se pagan con scopes de agentes. /v1/message-templates no tiene scope propio: listarlas y consultar su conexión exigen agents:read; crearlas y borrarlas, agents:write — el mismo permiso que crea, modifica y borra agentes. No hay forma de emitir una llave que gestione plantillas de WhatsApp sin conceder también eso. Si falta el scope, el 403 responde Insufficient scope for this operation, sin nombrar cuál.
Los scopes no admiten comodines. El guard compara cadenas exactas, así que agents:* no autoriza nada — hay que listar agents:read y agents:write por separado. Una llave con un scope inexistente se emite sin error y falla más tarde con un 403 que no dice cuál falta.
Recomendaciones rápidas:
  • Define scopes por entorno y flujo de negocio (backoffice, automatizaciones, integraciones externas, etc.).
  • Evita entregar *:* o :write cuando tu integración sólo consulta información.
  • Valida en openapi/public-api.yaml si un endpoint exige scopes adicionales o específicos.