Autenticação
Chaves de API, escopos e o que nunca colocar no navegador.
Toda requisição à API da Amivu é autenticada por uma chave, enviada no cabeçalho Authorization. Não há sessão, cookie ou fluxo de login: a chave age em nome da organização, e não de uma pessoa.
curl https://api.amivu.com.br/v1/contacts \
-H "Authorization: Bearer amivu_live_k3Hw9fA2..."
A chave
Ela nasce no painel, em Configurações → Desenvolvedores. O prefixo diz o ambiente a olho nu:
amivu_live_…alcança dados reais e envia mensagens de verdade.amivu_test_…alcança um sandbox isolado e não envia nada para ninguém.
O segredo aparece uma única vez, no momento da criação. Depois disso, o painel mostra só o suficiente para você reconhecê-la numa lista:
amivu_live_k3Hw••••••••7Hax
Isso não é uma limitação da interface — é o desenho. O banco guarda apenas o resumo criptográfico da chave, então nem nós conseguimos recuperá-la. Perdeu, cria outra e revoga a antiga; nenhuma outra integração é afetada.
Escopos
Cada chave carrega uma lista de escopos, e cada rota exige um. Uma chave sem o escopo da rota recebe 403 com insufficient_scope — nunca um resultado parcial.
Leitura e escrita são sempre separadas, e uma nunca implica a outra. Um agente de IA que só precisa ler o histórico e responder leva conversations:read e messages:write — e continua incapaz de apagar um contato.
Contatos
contacts:read- Ler contatos, incluindo etiquetas e campos personalizados.
contacts:write- Criar, atualizar e remover contatos.
Conversas
conversations:read- Ler conversas e seus metadados.
conversations:write- Abrir conversas, atribuir, encerrar e reabrir.
Mensagens
messages:read- Ler mensagens e o estado de entrega delas.
messages:write- Enviar mensagens de texto e mídia nas conversas, e subir os anexos delas. Modelo aprovado ainda não sai pela API.
Canais
channels:read- Listar canais conectados e as capacidades de cada um.
Atendentes e times
users:read- Listar os atendentes da organização.
teams:read- Listar times e seus integrantes.
teams:write- Criar e atualizar times.
Etiquetas e notas
tags:read- Listar etiquetas.
tags:write- Criar, atualizar e remover etiquetas; aplicá-las a conversas.
notes:read- Ler notas internas de uma conversa.
notes:write- Escrever notas internas.
Modelos
templates:read- Listar modelos de mensagem aprovados.
templates:write- Gerenciar modelos de mensagem.
Campos personalizados
custom_fields:read- Ler o catálogo de campos personalizados.
custom_fields:write- Criar e atualizar campos personalizados.
Webhooks
webhooks:read- Listar endpoints de webhook e as entregas deles.
webhooks:write- Criar, atualizar e remover endpoints de webhook.
Relatórios e auditoria
analytics:read- Ler relatórios agregados de atendimento.
audit_logs:read- Ler a trilha de auditoria da organização.
Onde guardar a chave
Guarde-a como variável de ambiente ou num cofre de segredos. Se ela vazar, revogue no painel: a revogação vale na requisição seguinte, e a linha da chave permanece para a trilha de auditoria continuar fazendo sentido.
Quando a API recusa
As recusas de credencial são específicas de propósito — elas mandam você a lugares diferentes:
| Código | HTTP | O que fazer |
|---|---|---|
| missing_api_key | 401 | O cabeçalho não veio. Confira o formato `Bearer`. |
| invalid_api_key | 401 | A chave não existe. Provavelmente erro de digitação. |
| revoked_api_key | 401 | Alguém a revogou no painel. Crie outra. |
| expired_api_key | 401 | Passou da data de expiração definida na criação. |
| insufficient_scope | 403 | A chave existe e não alcança esta rota. O erro diz qual escopo falta. |
Todos seguem o formato único de erro, com o request_id que identifica a chamada no Registro de chamadas do painel.
Escrevemos sobre operação de atendimento, canais e IA no blog da Amivu.