EntrarTeste grátis

API · Atualizado em 12/10/2026

Autenticação e chaves de API

Crie uma chave de API na Gestão, use o cabeçalho Bearer ou Key, entenda chave de fluxo, de organização e de IA e saiba restringir por IP.

Neste artigo
  1. Quando usar
  2. Pré-requisitos
  3. Passo a passo
  4. Formatos do cabeçalho
  5. Tipos de chave
  6. Endereço da API
  7. Restringir a chave por IP
  8. Limite de tentativas erradas
  9. Resultado esperado
  10. Problemas comuns
  11. Boas práticas
  12. Próximos passos
  13. Perguntas frequentes

Toda chamada à API precisa de uma chave de API. A chave diz quem está chamando, a que fluxo ela pertence e o que ela pode fazer (os escopos). Não há login, cookie ou OAuth: a chave vai em um cabeçalho de cada requisição.

Quando usar

Sempre que um sistema seu for chamar a API. Use uma chave por integração, para poder revogar uma sem afetar as outras.

Pré-requisitos

  • Acesso às configurações do fluxo na Gestão.
  • Saber o que a integração vai fazer, para marcar só os acessos necessários.

Passo a passo

  1. Na Gestão, abra o fluxo e vá em Configurações, depois Chaves de acesso.
  2. Clique em Nova chave e dê um nome que diga para que ela serve, como "Integração CRM".
  3. Se a integração veio da Blip e usa comandos, marque Compatível com a Blip. Se for para um agente de IA, use o campo Agente de IA (MCP). Para uma integração comum, deixe os dois em branco.
  4. Salve e copie o que aparece. A tela mostra a chave de acesso, o identificador do fluxo e os dois formatos de cabeçalho prontos.
  5. Guarde a chave em um cofre de segredos ou em variável de ambiente.

Formatos do cabeçalho

FormatoCabeçalhoQuando usar
BearerAuthorization: Bearer pipe_exemplo_...Padrão para integrações novas
KeyAuthorization: Key <base64(identificador:chave)>Integrações que já usam o estilo da Blip

O identificador é o nome curto do fluxo, exibido na criação da chave. Para montar o cabeçalho Key no terminal:

IDENT="meu-fluxo"
CHAVE="pipe_exemplo_000000000000000000000000"
KEY=$(printf %s "$IDENT:$CHAVE" | base64 -w0)
curl -s https://http.pipebr.app/v1/queues -H "Authorization: Key $KEY"

O Pipe só confere o identificador. Quem decide a conta e o fluxo é o prefixo da chave. Identificador diferente, base64 inválido, chave revogada, expirada ou errada dão todos o mesmo 401, para não revelar o que falhou.

Tipos de chave

TipoAlcanceObservações
Chave de fluxoSó o fluxo dono da chave (num roteador, também os serviços dele)É a criada na Gestão. Recursos de outros fluxos respondem 404
Chave de roteadorO roteador e seus serviçosFunciona como chave de fluxo, no roteador
Chave da organizaçãoToda a contaNão pode usar o formato Key nem a rota /commands. Serve nas rotas /v1 com Bearer
Chave de IA (MCP)Os escopos do nível escolhido: leitura, propostas de mudança ou completoVeja Como conectar um agente de IA

Chaves de fluxo nascem com estes escopos: conversas:ler, conversas:escrever, mensagens:ler, mensagens:escrever, contatos:ler, contatos:escrever, filas:ler e atendentes:ler. A opção Compatível com a Blip acrescenta comandos:executar, contexto:escrever, relatorios:ler e atendentes:escrever.

Endereço da API

EndereçoUso
https://http.pipebr.appEndereço para integrações com chave de API. Sem CORS e sem cookies
https://api.pipebr.appAtende o aplicativo e, por enquanto, o mesmo conjunto de rotas por chave

Prefira http.pipebr.app em integrações novas. Como a API é feita para servidores, ela não responde a chamadas feitas direto do navegador (sem cabeçalhos CORS).

Restringir a chave por IP

Uma chave pode aceitar chamadas só de IPs ou faixas (CIDR) que você informar, até 20 itens. Fora da lista, a resposta é 403 com o código ip_not_allowed. Hoje essa restrição não tem tela na Gestão: ela é definida pela rota de gestão de chaves do fluxo, com ipPermitidos na criação ou na alteração da chave.

Limite de tentativas erradas

Depois de 20 falhas de autenticação por minuto vindas do mesmo IP, o Pipe responde 429 com o cabeçalho Retry-After até a janela de 60 segundos terminar. Chamadas com chave válida nunca entram nessa conta. Quem compartilha o mesmo IP de saída (NAT) com um sistema que erra a chave pode ver 429 por até 1 minuto.

Resultado esperado

Com a chave certa, a chamada responde 200 ou 201. Sem ela, 401 com este corpo:

{
  "error": {
    "code": "not_authorized",
    "message": "Chave de API ausente ou inválida."
  }
}

Problemas comuns

  • 401 "Chave revogada." ou "Chave expirada.": a chave foi desativada. Crie outra e atualize a integração.
  • 401 com o formato Key: confira se o base64 é de identificador:chave, sem quebra de linha, e se o identificador é o do fluxo dono da chave.
  • 401 com chave da organização no formato Key: esse formato só aceita chaves de fluxo ou de roteador. Use Bearer.
  • 403 tenant_mismatch: o endereço usado é de outra conta. Use https://http.pipebr.app.
  • Limite de chaves: cada fluxo mantém até 3 chaves ativas. Revogue uma antes de criar outra.

Boas práticas

  • Troque as chaves de tempos em tempos: crie a nova, atualize a integração e revogue a antiga.
  • Não use a chave de uma pessoa ou de outra integração em um serviço novo.
  • Marque só os acessos de que a integração precisa. Veja Escopos e permissões.
  • Revogue imediatamente uma chave que tenha vazado.

Próximos passos

Perguntas frequentes

Onde crio a chave de API?

Na Gestão, abra o fluxo, vá em Configurações e Chaves de acesso e crie uma nova chave. O valor completo aparece uma única vez, na criação.

Quantas chaves cada fluxo pode ter?

Até 3 chaves ativas ao mesmo tempo por fluxo. Para criar outra, revogue uma existente.

Qual a diferença entre Bearer e Key?

Os dois autenticam a mesma chave. Bearer envia só o token. Key envia o identificador do fluxo e o token juntos, em base64, no formato usado por integrações vindas da Blip.

Perdi a chave. Dá para ver de novo?

Não. O Pipe guarda apenas uma impressão (hash) do segredo. Crie uma chave nova, atualize sua integração e revogue a antiga.