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

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. 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.

Role para o lado para ver o diagrama inteiro

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.

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, e o passo a passo está em autocadastro e reivindicação de agentes.

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, é 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. 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.

{
  "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 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.

Role para o lado para ver o diagrama inteiro

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.
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 mostra os dois caminhos para conseguir uma chave. Comece com uma chave write e só acrescente publish quando os rascunhos tiverem conquistado isso.