Keys

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

Obtener tu API Key

Inicia sesión en Agents Studio.
Ve a Ajustes (Settings) del espacio de trabajo actual.
Abre la sección “API Keys”.
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):

X-API-Key: TU_API_KEY

Ejemplo de uso (HTTP):

GET /v1/agents?limit=1 HTTP/1.1
Host: api-prod.studio.getsupervisor.ai
X-API-Key: TU_API_KEY
X-Workspace-Id: TU_WORKSPACE_ID

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.

Scope	Permiso principal
`agents:read`	Listar y consultar agentes del workspace.
`agents:write`	Crear/actualizar/eliminar agentes y gestionar su configuración operativa.
`agent-versions:read`	Listar y consultar versiones de un agente.
`agent-versions:write`	Crear, clonar, restaurar y publicar versiones de un agente.
`agent-instructions:read`	Leer instrucciones (a nivel agente y por versión).
`agent-instructions:write`	Crear, actualizar o borrar instrucciones personalizadas.
`agent-blueprints:read`	Consultar el blueprint (personalidad) de una versión de agente.
`agent-blueprints:write`	Editar blueprint: personalidad, reglas, audiencia, objetivos, etc.
`blueprint-stages:read`	Listar y consultar stages del blueprint.
`blueprint-stages:write`	Crear, actualizar o reordenar stages del blueprint.
`stage-triggers:read`	Consultar triggers que conectan stages y sus condiciones.
`stage-triggers:write`	Crear, actualizar o eliminar triggers entre stages.
`agent-schedules:read`	Consultar horario semanal y excepciones vigentes.
`agent-schedules:write`	Crear o modificar horarios y excepciones.
`campaigns:read`	Consultar campañas y sus ejecuciones.
`campaigns:write`	Crear y disparar campañas batch.
`calls:read`	Consultar llamadas (Speech Analytics) del workspace.
`catalogs:read`	Navegar catálogos globales y por workspace (idiomas, tonos, voces, etc.).
`catalogs:write`	Registrar o ajustar ítems de catálogo.
`tools:read`	Descubrir tools disponibles, recursos y capacidades declaradas.
`tools:connections:read`	Listar conexiones configuradas entre agentes y tools.
`tools:connections:write`	Crear o actualizar conexiones entre agentes y tools.
`tools:execute`	Ejecutar acciones de una tool.
`webhooks:read`	Listar webhooks y sus suscripciones activas.
`webhooks:write`	Crear, actualizar o eliminar webhooks y suscripciones.
`api-keys:read`	Listar credenciales existentes y revelar su valor.
`api-keys:write`	Emitir o revocar API Keys.
`workspaces:read`	Consultar workspaces disponibles y sus metadatos.

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.

Documentación

API Reference

MCP

Conocimiento

Blueprint

Plantillas

Misceláneos

Notificaciones

Obtener tu API Key

Alcance y permisos

Uso en peticiones

Rotación y buenas prácticas

Scopes disponibles

​Obtener tu API Key

​Alcance y permisos

​Uso en peticiones

​Rotación y buenas prácticas

​Scopes disponibles

Obtener tu API Key

Alcance y permisos

Uso en peticiones

Rotación y buenas prácticas

Scopes disponibles