# Chaves de API para agentes: read, write, publish e um log de auditoria que você vai mesmo consultar

_2026-10-01 · Como dar chaves de API do Shager a agentes com segurança: o que read, write e publish permitem, a reivindicação, o armazenamento, a rotação e a auditoria._

Dê a cada agente a chave do Shager mais restrita que dê conta do trabalho dele: `read` para relatórios, `write` para rascunhos e `publish` só para a etapa que agenda os posts. Guarde as chaves em variáveis de ambiente ou na configuração do cliente MCP, nunca nos prompts. Revogue e faça a rotação pelo painel de agentes, e leia o log de auditoria dele, que lista cada chamada feita por um agente, pelo menos uma vez por semana enquanto um agente novo estiver se acomodando.

Essa é a política. O resto do artigo explica o raciocínio e a mecânica, porque uma política que ninguém entende é contornada na primeira vez que atrapalha.

## O que cada escopo pode fazer?

Toda chave do Shager tem um ou mais de três escopos. Cada operação da API declara o escopo de que precisa; ele aparece como `x-scope` em cada operação no [documento OpenAPI](https://app.shager.ai/api/v1/openapi.json). As ferramentas MCP são as mesmas operações, então as mesmas regras valem pelo MCP.

| Escopo | Operações |
|---|---|
| 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 |

Duas coisas nessa tabela merecem atenção.

A primeira: `publish` tem uma única operação, e é justamente a que coloca o conteúdo no ar nas contas dos clientes. Isolá-la é o objetivo. Um agente pode fazer quase todo o trabalho, desde subir as mídias até escrever as legendas de cada conta e enviar os links de aprovação, sem nunca conseguir colocar um post em uma página.

A segunda: `cancel_post` fica em `write`. Um agente que só faz rascunhos consegue puxar um post agendado de volta para rascunho. Isso é proposital: interromper um erro deve ser mais fácil do que cometê-lo.

Uma chave usada sem o escopo necessário recebe um erro no formato padrão, `{ "error": { "code", "message" } }`, com HTTP 403. O agente deve relatar esse erro em vez de procurar outro caminho para contorná-lo, e as suas instruções permanentes devem dizer isso.

## De onde vêm as chaves

Há dois caminhos.

**Uma pessoa cria a chave** em `app.shager.ai/dashboard/agents`, escolhendo os escopos. Esse é o caminho normal para uma agência que está adicionando um agente a uma conta existente.

**O agente se cadastra sozinho.** Um agente sem conta chama `POST https://app.shager.ai/api/v1/agent/signup` com um `agent_name` e, de preferência, um `contact_email` da pessoa responsável por ele. Ele recebe uma `api_key`, mostrada uma única vez, e um `claim_url`. Essa chave funciona na hora em um sandbox, que pode criar até cinco espaços de trabalho, subir mídias, criar rascunhos e ler. Ela não pode agendar nem publicar, criar links de conexão para clientes nem enviar pedidos de aprovação.

```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"}'
```

Essas restrições só caem quando uma pessoa abre o `claim_url`, faz login e reivindica a organização. Nesse momento, ela decide se a chave do agente também recebe `publish`. Se ninguém reivindicar, o sandbox expira em sete dias. A receita completa está publicada em [/auth.md](/auth.md), e o passo a passo está em [autocadastro e reivindicação de agentes](/en/blog/agent-self-signup-and-claim).

A decisão de design por trás disso é simples: um agente pode explorar e preparar tudo sozinho, mas conectar contas reais e publicar nelas sempre passa por uma pessoa.

## Como os agentes devem guardar e enviar as chaves?

As chaves do Shager são bearer tokens enviados como `Authorization: Bearer shgr_live_...`. A característica que define um bearer token, nas palavras da [RFC 6750](https://www.rfc-editor.org/rfc/rfc6750), é que qualquer um que o tenha em mãos pode usá-lo. Nada além dele comprova a identidade. Então, todo o trabalho consiste em não deixá-lo vazar.

Na prática:

1. **Variáveis de ambiente, referenciadas pela configuração.** O Claude Code aceita a expansão `${VAR}` nos cabeçalhos do `.mcp.json`, segundo a sua [documentação de MCP](https://code.claude.com/docs/en/mcp). O arquivo pode ir para o repositório; a chave fica no ambiente.
2. **Nunca em um prompt.** Uma chave colada no chat acaba em transcrições e logs, e às vezes em conversas compartilhadas.
3. **Nunca na pasta de um cliente.** Se você mantém pastas de contexto por cliente, as chaves não devem ficar nelas. Essas pastas são compartilhadas e compactadas por aí.
4. **Uma chave por função de agente.** Um job de relatórios, um agente de rascunhos e uma etapa de agendamento não devem compartilhar a mesma chave. Quando uma vazar, você revoga só uma.

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

O servidor MCP do Shager aceita esse cabeçalho de chave de API. Clientes que se conectam com login via OAuth, como um conector personalizado no Claude ou no ChatGPT, têm o mesmo tipo de controle: uma pessoa aprova a conexão na tela de consentimento do Shager, a publicação é uma caixa de seleção separada que vem desmarcada, e a conexão aparece no mesmo registro de auditoria. O artigo [Shager e ChatGPT](/en/blog/shager-and-chatgpt) mostra a configuração no ChatGPT.

## Rotação sem tempo fora do ar

As chaves devem ser trocadas quando alguém com acesso sai da equipe, quando uma chave pode ter sido exposta e em uma periodicidade que você consiga manter. A sequência que evita qualquer interrupção:

1. Crie no painel uma chave nova com os mesmos escopos.
2. Atualize a variável de ambiente onde o agente roda.
3. Rode `whoami` com a chave nova para confirmar que ela funciona e mostra os escopos esperados.
4. Revogue a chave antiga.

A revogação vale para toda chamada feita com aquela chave, tanto pelo MCP quanto pela REST.

## O limite de requisições também é segurança

Cada chave tem um limite de 120 requisições por minuto. Um agente bem-comportado nunca chega perto: um rascunho semanal completo para um cliente são algumas dezenas de chamadas. Quando um agente recebe HTTP 429, geralmente é sinal de loop, de um agente repetindo a mesma chamada que falha sem parar. As suas instruções devem tratar o 429 como sinal para parar, não como motivo para tentar mais rápido. Recue, relate e deixe uma pessoa olhar.

## Lendo o log de auditoria

O painel de agentes mostra um log de auditoria com cada chamada feita por um agente. Ele só serve se alguém ler. O que procurar nas primeiras semanas com um agente novo:

1. **Chamadas inesperadas.** Um agente de relatórios chamando `create_post` significa que as instruções ou a chave dele estão erradas.
2. **Desvio de espaço de trabalho.** Chamadas que mexem em um cliente que não tinha nada a ver com a tarefa. É o primeiro alerta do erro entre clientes que discutimos em [um agente, vários clientes](/en/blog/one-agent-many-clients).
3. **Rajadas de erros.** 403 repetidos significam que o agente insiste em algo fora do seu escopo. Corrija as instruções, não o escopo.

Depois de algumas semanas sem problemas, uma olhada rápida por semana basta.

## Perguntas frequentes

### O agente deveria ter o escopo publish em algum momento?

Pode ter, quando você já confiar nos rascunhos dele e tiver uma etapa de revisão, seja com links de aprovação do cliente, seja com um revisor interno. Um padrão que funciona bem é deixar o `publish` em uma chave separada, usada só por uma etapa de agendamento curta e roteirizada, para que o agente que escreve não seja o mesmo que publica.

### O que acontece com a chave do agente quando o sandbox é reivindicado?

A organização passa a ser da pessoa, e a chave continua funcionando dentro dela. Na reivindicação, a pessoa escolhe se essa chave também pode agendar e publicar. Ela pode revogá-la ou criar outras no painel a qualquer momento.

### Dá para limitar uma chave a um único espaço de trabalho de cliente?

Os escopos limitam o que uma chave pode fazer, não em qual espaço de trabalho ela age. Separe os clientes por espaço de trabalho, com contexto próprio de cada cliente e o hábito de localizar o espaço de trabalho pelo nome antes de cada escrita, e use chaves separadas por função para que a revogação continue cirúrgica.

## Para onde ir agora

Se você está configurando o seu primeiro agente, a [porta de entrada para agentes](/en/agents) mostra os dois caminhos para conseguir uma chave. Comece com uma chave `write` e só acrescente `publish` quando os rascunhos tiverem conquistado isso.

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