EntrarTeste grátis

API · Atualizado em 12/10/2026

Escopos e permissões da chave de API

Veja o que cada escopo da chave de API libera, quais vêm por padrão, como o fluxo limita a chave e o que fazer ao receber 403 ou 404.

Neste artigo
  1. Quando usar
  2. Pré-requisitos
  3. Escopos de integração
  4. Quais escopos cada chave tem
  5. O fluxo limita a chave
  6. Passo a passo: descobrir qual escopo falta
  7. Resultado esperado
  8. Problemas comuns
  9. Boas práticas
  10. Próximos passos
  11. Perguntas frequentes

Os escopos dizem o que a chave pode fazer. O fluxo dono da chave diz onde ela pode agir. Juntos eles limitam o estrago de uma chave vazada e deixam cada integração com o mínimo de acesso.

Quando usar

Antes de criar a chave de uma integração nova, para decidir o conjunto de acessos, e ao investigar um erro 403.

Pré-requisitos

  • Conhecer as rotas que a integração vai chamar. As tabelas de cada artigo da API trazem o escopo de cada rota.

Escopos de integração

EscopoO que libera
conversas:lerListar e ler tickets, ver etiquetas, listar sessões presas no bot
conversas:escreverAbrir ticket, transferir, encerrar, pôr em espera e etiquetar tickets
mensagens:lerLer mensagens, histórico do contato, campanhas, mensagens ativas, agendamentos, modelos e respostas rápidas
mensagens:escreverEnviar mensagens, anexos e reações, disparar mensagens ativas e campanhas, criar e cancelar agendamentos
contatos:lerLer contatos, etiquetas de contato e variáveis de contexto
contatos:escreverCriar e editar contatos e etiquetá-los
contexto:escreverGravar e apagar variáveis de contexto e mudar o bloco do contato no bot
filas:lerLer filas, regras de atribuição e horário de atendimento
atendentes:lerLer atendentes e quem está online em uma fila
atendentes:escreverMudar o status de presença de um atendente
relatorios:lerRelatórios, histórico de tickets encerrados e monitoramento do dia
webhooks:lerLer os webhooks e as entregas de eventos
comandos:executarUsar a rota de comandos no formato da Blip

Existem também escopos usados só por agentes de IA (como config:ler, config:escrever e fluxos:escrever). Eles estão descritos em Escopos da chave de IA.

Quais escopos cada chave tem

Como a chave foi criadaEscopos
Padrão (chave de fluxo)conversas:ler, conversas:escrever, mensagens:ler, mensagens:escrever, contatos:ler, contatos:escrever, filas:ler, atendentes:ler
Compatível com a BlipO padrão, mais comandos:executar, contexto:escrever, relatorios:ler e atendentes:escrever
Agente de IA (MCP)O nível escolhido (veja o artigo do MCP)

A opção Compatível com a Blip só vale na criação: chaves existentes não ganham escopos sozinhas. Para mais acessos, crie uma chave nova.

O fluxo limita a chave

Uma chave de fluxo só enxerga e altera dados do próprio fluxo, e, quando o fluxo é um roteador, dos serviços dele:

  • contatos que têm conversa ou sessão de bot no fluxo;
  • tickets, filas, atendentes, etiquetas, canais e agendamentos do fluxo.

Qualquer filtro que você enviar (por exemplo flowId) só estreita o resultado. Pedir um recurso de outro fluxo devolve 404, nunca 403, para não confirmar que o recurso existe.

Passo a passo: descobrir qual escopo falta

  1. Veja o corpo do erro 403. Ele traz o escopo que faltou:
{
  "error": {
    "code": "without_scope",
    "message": "A chave não tem o escopo \"contatos:escrever\".",
    "detalhe": { "scope": "contatos:escrever" }
  }
}
  1. Crie uma chave nova com a opção que inclui esse escopo.
  2. Troque a chave na integração e revogue a antiga.

Resultado esperado

A integração faz só o que o conjunto de escopos permite, e cada falta de permissão aparece como 403 com o nome do escopo.

Problemas comuns

  • 403 without_scope ao mudar status de atendente: a rota POST /v1/agents/status exige atendentes:escrever. O escopo de leitura não basta.
  • 403 key_of_flow ou key_of_other_flow: a rota é de gestão e a chave de fluxo só vale nas rotas da API pública, ou o fluxo informado não é o da chave.
  • 403 financial_state_read_only: a conta está em somente leitura por pendência de assinatura. Leituras continuam funcionando; escritas são recusadas até regularizar em Contrato.
  • 403 ip_not_allowed: a chave tem lista de IPs e a chamada veio de fora dela.

Boas práticas

  • Dê a cada integração só os escopos de que ela precisa. Uma integração que só lê relatórios não precisa de mensagens:escrever.
  • Separe leitura e escrita em chaves diferentes quando fizer sentido.
  • Revise as chaves ativas de tempos em tempos e revogue as que ninguém usa.

Próximos passos

Perguntas frequentes

O que é um escopo?

É uma permissão da chave, no formato recurso:ação, como contatos:ler. Cada rota exige um ou mais escopos. Sem eles, a resposta é 403 without_scope.

Como dar um escopo novo a uma chave?

Os escopos são definidos na criação da chave. As opções da tela são o conjunto padrão, Compatível com a Blip e os níveis de Agente de IA. Para um conjunto diferente, crie uma chave nova com a opção adequada.

Por que recebo 404 em vez de 403?

Chaves de fluxo só enxergam o próprio fluxo. Um recurso de outro fluxo responde 404 para não confirmar que ele existe.

A chave da organização tem todos os escopos?

Ela vale para a conta toda, mas continua limitada aos escopos marcados nela. Uma chave com o escopo curinga (*) tem todos.