Autenticação

Toda requisição à API da Onvox AI deve ser autenticada com uma API Key enviada no header X-API-Key.

Header obrigatório

X-API-Key: evai_your_key_here
Content-Type: application/json

X-API-Key vai em todas as requisições: sem ele, ou com uma chave inválida, a resposta é 401 Unauthorized. Content-Type: application/json é exigido em POST /api/analyses: sem ele, a resposta é 415 (UNSUPPORTED_MEDIA_TYPE), devolvida antes de a chave ser conferida.

Como obter sua API Key

Só usuários admin_company ou super_admin podem criar uma API Key. Usuários salesperson ou supervisor recebem 403 Forbidden ao tentar.

Acesse o Dashboard da Onvox AI, logado como admin_company (ou super_admin)
Vá em Configurações, no card Chaves de API
Clique em Nova Chave
Defina um nome descritivo (ex: Integração CRM, Script ETL)
Copie a chave gerada (ela só é exibida uma vez)

Após fechar o modal de criação, a chave completa não pode ser recuperada. Salve-a imediatamente em um gerenciador de segredos (Vault, AWS Secrets Manager, variável de ambiente, etc.).

Verificar autenticação

Não existe um endpoint dedicado de "verificar chave". Use qualquer um dos endpoints reais da API. GET /api/salespersons é o mais leve pra esse teste (não precisa de corpo nem parâmetros):

curl -X GET 'https://api.evolu-ai.com/api/salespersons' \
  -H 'X-API-Key: evai_your_key_here'

Uma resposta 200 (mesmo que a lista venha vazia, []) confirma que a chave está válida e ativa. 401 Unauthorized indica chave ausente, incorreta ou revogada. 403 Forbidden neste teste indica chave válida sem o escopo api:salespersons:read (a mensagem traz o motivo; ver Permissões e escopo, abaixo).

Permissões e escopo

A API Key não herda o papel de quem a criou. O que ela carrega é uma lista de escopos, e o escopo diz quais endpoints a chave alcança:

Escopo	Libera
`api:*`	Tudo, inclusive endpoint criado depois da chave
`api:analyses:read`	Leitura de análise: `GET /api/analyses` e `GET /api/analyses/{id}`
`api:analyses:write`	Criação de análise: `POST /api/analyses`
`api:salespersons:read`	`GET /api/salespersons`

O escopo é por recurso + ação, nunca por endpoint: quando um endpoint novo de leitura de análise entra no ar, ele cai em api:analyses:read, o escopo que a chave já tem. Nenhuma chave precisa ser recriada por causa de endpoint novo.

Chamar um endpoint sem o escopo correspondente devolve 403 Forbidden, e a mensagem diz qual escopo falta (ver Erros). Chave ausente, incorreta, revogada ou expirada continua sendo 401 Unauthorized — 401 é "não sei quem você é", 403 é "sei quem você é, e essa chave não alcança isto".

Há mais dois casos de 403 com chave válida:

Permissões inválidas: a chave traz um valor de permissões que a API não reconhece. Toda chamada responde 403 com Chave de API com permissões inválidas. Gere uma chave nova no painel (escopo exigido por este endpoint: <escopo>).
Empresa desativada: enquanto a empresa estiver desativada, toda chave dela responde 403 em qualquer endpoint, com A empresa "<nome>" está desativada desde <data>. As chaves de API não respondem enquanto isso.

Escopo não substitui o isolamento por empresa. Mesmo uma chave api:* só enxerga dados da empresa dela (companyId). Pedir uma análise de outra empresa devolve 404 Not Found, nunca o dado.

Chave criada antes dos escopos continua com acesso total, sem nenhuma ação sua. O controle de escopo passou a valer depois que muitas integrações já estavam no ar, e nenhuma delas perde acesso: a chave antiga é reconhecida como legada e alcança tudo que alcançava. Se quiser limitar uma integração antiga, crie uma chave nova com o escopo desejado e troque no cliente.

Chave criada pelo painel hoje nasce com api:* (o mesmo acesso total de sempre, só que declarado na chave). Uma chave "só leitura" já é possível no modelo, mas a escolha do escopo ainda não está exposta na tela — peça ao time da Onvox AI enquanto o controle não chega ao painel.

Boas práticas de quantidade de chaves

Não há um teto técnico fixo de API Keys por empresa hoje, mas é boa prática manter poucas chaves ativas (uma por integração real) e revogar as que não estão mais em uso, facilitando a auditoria e reduzindo a superfície de exposição caso uma chave vaze.

Boas práticas de segurança

Nunca exponha sua API Key em:

Código-fonte versionado (Git, GitHub, GitLab)
Frontend/browser (JavaScript do lado do cliente)
Logs de aplicação
URLs como query params

Use sempre:

Variáveis de ambiente no servidor (process.env.EVOLUA_API_KEY)
Gerenciadores de segredos em produção
Rotação periódica das chaves (recomendado a cada 90 dias)

# Exemplo: variável de ambiente
export EVOLUA_API_KEY="evai_your_key_here"

// No código
const API_KEY = process.env.EVOLUA_API_KEY;

Gerenciar API Keys

API Keys são gerenciadas só pelo painel web (usuário logado com sessão de navegador), pois não existe endpoint de API para listar, criar ou revogar chaves programaticamente. Se você precisa automatizar a rotação de chaves, use a mesma sequência de passos de Como obter sua API Key (acima) através de um usuário admin_company dedicado.

Pra revogar uma chave: em Configurações, no card Chaves de API, localize a chave e clique no ícone de lixeira. O clique exclui a chave na hora, sem pedir confirmação.

A revogação é imediata e irreversível. Requisições feitas depois disso falham com 401 Unauthorized; a chave só é conferida no início de cada requisição, então uma requisição que já estava em andamento termina normalmente.

Autenticação

Nesta página