# Claves de API para agentes: leer, escribir, publicar y un registro de auditoría que de verdad vas a revisar

_2026-10-01 · Cómo dar claves de API de Shager a agentes de IA con seguridad: read, write y publish, el reclamo del sandbox, almacenamiento, límites, rotación y auditoría._

Dale a cada agente la clave de Shager más acotada que cubra su tarea: `read` para los reportes, `write` para redactar y `publish` solo para el paso que programa las publicaciones. Guarda las claves en variables de entorno o en la configuración del cliente MCP, nunca en los prompts. Revoca y rota desde el panel de agentes, y lee su registro de auditoría, que muestra cada llamada que hace un agente, al menos una vez por semana mientras un agente nuevo se asienta.

Esa es la política. El resto del artículo explica el porqué y el cómo, porque una política que nadie entiende se salta la primera vez que resulta incómoda.

## ¿Qué permite cada permiso?

Cada clave de Shager tiene uno o más de tres permisos. Cada operación de la API declara el permiso que necesita; puedes verlo como `x-scope` en cada operación del [documento OpenAPI](https://app.shager.ai/api/v1/openapi.json). Las herramientas MCP son las mismas operaciones, así que por MCP se aplican las mismas reglas.

| Permiso | Operaciones |
|---|---|
| read | whoami, list_workspaces, list_channels, list_groups, list_posts, get_post, get_analytics |
| write | create_workspace, create_connect_link, create_group, upload_media_from_url, create_post, request_approval, cancel_post |
| publish | schedule_post |

Hay dos cosas de esa tabla que merecen atención.

La primera: `publish` contiene una sola operación, y es la que pone el contenido en vivo en las cuentas de los clientes. Aislarla es justamente la idea. Un agente puede hacer casi todo el trabajo, desde subir medios hasta redactar textos por cuenta y enviar enlaces de aprobación, sin poder nunca colocar una publicación en una página.

La segunda: `cancel_post` está dentro de `write`. Un agente que redacta puede devolver una publicación programada a borrador. Es a propósito: frenar un error debería ser más fácil que cometerlo.

Una clave que se usa sin el permiso necesario recibe un error con el formato estándar, `{ "error": { "code", "message" } }`, con HTTP 403. Los agentes deberían informar ese error en lugar de buscar otra forma de rodearlo, y tus instrucciones permanentes deberían decirlo.

## De dónde salen las claves

Hay dos caminos.

**Una persona crea la clave** en `app.shager.ai/dashboard/agents` y elige los permisos. Es el camino habitual cuando una agencia suma un agente a una cuenta que ya existe.

**El agente se registra solo.** Un agente sin cuenta llama a `POST https://app.shager.ai/api/v1/agent/signup` con un `agent_name` e, idealmente, un `contact_email` de la persona responsable. Recibe una `api_key`, que se muestra una sola vez, y un `claim_url`. Esa clave funciona de inmediato en un sandbox, que puede crear hasta cinco clientes, subir medios, crear borradores y leer. No puede programar ni publicar, crear enlaces de conexión para clientes ni enviar solicitudes de aprobación.

```bash
curl -s https://app.shager.ai/api/v1/agent/signup \
  -H "Content-Type: application/json" \
  -d '{"agent_name":"Northwind content agent (Claude Code)",
       "contact_email":"ops@northwind-agency.example",
       "purpose":"Draft weekly posts for 3 retail clients"}'
```

Esas restricciones se levantan solo cuando una persona abre `claim_url`, inicia sesión y reclama la organización. En ese momento la persona decide si la clave del agente también recibe `publish`. Si nadie la reclama, el sandbox vence a los siete días. La receta completa está publicada en [/auth.md](/auth.md), y el paso a paso está en [alta autónoma y reclamo de agentes](/en/blog/agent-self-signup-and-claim).

La decisión de diseño detrás de esto es simple: un agente puede explorar y preparar por su cuenta, pero conectar cuentas reales y publicar en ellas siempre pasa por una persona.

## ¿Cómo deberían guardar y enviar las claves los agentes?

Las claves de Shager son tokens de portador que se envían como `Authorization: Bearer shgr_live_...`. La propiedad que define a un token de portador, como lo explica el [RFC 6750](https://www.rfc-editor.org/rfc/rfc6750), es que cualquiera que lo tenga puede usarlo. Ninguna otra cosa prueba la identidad. Así que todo el trabajo consiste en no filtrarlo.

En la práctica:

1. **Variables de entorno, referenciadas desde la configuración.** Claude Code admite la expansión `${VAR}` en las cabeceras de `.mcp.json`, según su [documentación de MCP](https://code.claude.com/docs/en/mcp). El archivo se puede subir al repositorio; la clave se queda en el entorno.
2. **Nunca en un prompt.** Una clave pegada en un chat termina en transcripciones y logs, y a veces en conversaciones compartidas.
3. **Nunca en la carpeta de un cliente.** Si mantienes carpetas de contexto por cliente, las claves no van ahí. Esas carpetas se comparten y se comprimen.
4. **Una clave por rol de agente.** Un trabajo de reportes, un agente que redacta y un paso de programación no deberían compartir clave. Cuando una se filtra, revocas una sola.

```json
{
  "mcpServers": {
    "shager": {
      "type": "http",
      "url": "https://app.shager.ai/api/mcp",
      "headers": { "Authorization": "Bearer ${SHAGER_DRAFT_KEY}" }
    }
  }
}
```

El servidor MCP de Shager acepta esta cabecera de clave de API. Los clientes que se conectan con inicio de sesión OAuth, como un conector personalizado en Claude o ChatGPT, tienen el mismo control: una persona aprueba la conexión en la pantalla de consentimiento de Shager, publicar es una casilla aparte que viene desactivada, y la conexión aparece en el mismo registro de auditoría. [Shager y ChatGPT](/en/blog/shager-and-chatgpt) explica cómo configurarlo en ChatGPT.

## Rotación sin interrupciones

Conviene rotar las claves cuando se va alguien que tenía acceso, cuando una clave pudo quedar expuesta y con una frecuencia que puedas sostener. La secuencia que evita cortes:

1. Crea una clave nueva con los mismos permisos en el panel.
2. Actualiza la variable de entorno donde corre el agente.
3. Ejecuta `whoami` con la clave nueva para confirmar que funciona y muestra los permisos esperados.
4. Revoca la clave anterior.

La revocación se aplica a todas las llamadas hechas con esa clave, tanto por MCP como por REST.

## Los límites de solicitudes también son seguridad

Cada clave está limitada a 120 solicitudes por minuto. Un agente que se porta bien nunca se acerca a ese número: el borrador semanal completo de un cliente son unas pocas decenas de llamadas. Cuando un agente recibe un HTTP 429, normalmente significa que hay un bucle: un agente que reintenta la misma llamada fallida una y otra vez. Tus instrucciones deberían tratar el 429 como una señal para detenerse, no como un motivo para reintentar más rápido. Esperar, informar y dejar que una persona lo revise.

## Cómo leer el registro de auditoría

El panel de agentes muestra un registro de auditoría con cada llamada de los agentes. Solo sirve si alguien lo lee. En qué fijarte durante las primeras semanas con un agente nuevo:

1. **Llamadas que no esperabas.** Si un agente de reportes llama a `create_post`, sus instrucciones o su clave están mal.
2. **Deriva entre clientes.** Llamadas que tocan un cliente que no tenía nada que ver con la tarea. Es la alerta temprana del error entre clientes que tratamos en [un agente, muchos clientes](/en/blog/one-agent-many-clients).
3. **Ráfagas de errores.** Varios 403 seguidos significan que el agente insiste en algo que está fuera de su permiso. Corrige las instrucciones, no el permiso.

Después de unas cuantas semanas limpias, basta con un vistazo rápido semanal.

## Preguntas frecuentes

### ¿El agente debería tener alguna vez el permiso publish?

Puede tenerlo, una vez que confíes en sus borradores y tengas un paso de revisión, ya sea con enlaces de aprobación para el cliente o con un revisor interno. Un patrón que funciona bien es dejar `publish` en una clave aparte que use solo un paso de programación corto y con script, para que el agente que escribe no sea el mismo que publica.

### ¿Qué pasa con la clave de un agente cuando se reclama el sandbox?

La organización pasa a ser de la persona y la clave sigue funcionando dentro de ella. En el momento del reclamo, la persona elige si esa clave también puede programar y publicar. Puede revocarla o crear claves nuevas desde el panel cuando quiera.

### ¿Se puede limitar una clave a un solo cliente?

Los permisos limitan lo que puede hacer una clave, no sobre qué cliente actúa. Separa a los clientes con espacios propios, con contexto por cliente y con la costumbre de resolver el cliente por su nombre antes de cada escritura, y usa claves distintas por rol para que la revocación sea quirúrgica.

## Por dónde seguir

Si estás configurando tu primer agente, el [punto de entrada para agentes](/en/agents) muestra los dos caminos para obtener una clave. Empieza con una clave `write` y agrega `publish` solo cuando los borradores se lo hayan ganado.

---
Source: https://shager.ai/es/blog/api-keys-scopes-and-audit