> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getsupervisor.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Keys

> Cómo obtener y usar tu API Key por espacio de trabajo

<Note>
  Las API Keys son <strong>por espacio de trabajo</strong>. Cada workspace tiene
  su propia clave y permisos asociados.
</Note>

## 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 <strong>workspace</strong> 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):

```http theme={null}
X-API-Key: TU_API_KEY
```

Ejemplo de uso (HTTP):

```http theme={null}
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.