Autenticação

Chaves secretas, chaves públicas, escopos e tokens de sessão para o front.

A API usa três tipos de credencial. Cada um tem um lugar certo.

Chaves secretas

Envie no cabeçalho Authorization:

curl https://api.nevox.ai/v1/agents \
  -H "Authorization: Bearer nvx_sk_live_..."

Gerenciamento

• Só o dono da conta gera chaves, em Painel → Desenvolvedores → Chaves de API.
• A chave aparece uma única vez. A Nevox guarda só uma versão criptografada (hash). Se perder, gere outra.
• Você pode ter várias chaves (uma por sistema) e revogar qualquer uma na hora. A revogação vale em até 1 minuto.
• O painel mostra o último uso de cada chave e o registro das chamadas, com os erros.
• Se uma chave aparecer num repositório público, revogue e gere outra imediatamente.

Escopos

Dê a cada chave só o que ela precisa. Os escopos dos recursos que ainda vão chegar podem ser marcados desde já: passam a valer quando o recurso chegar.

Uma chamada sem o escopo necessário recebe 403 com o código insufficient_scope.

Chaves públicas

A chave pública identifica sua conta no front. Ela só pode:

• carregar o widget do agente;
• enviar eventos de rastreamento de visitantes (/v1/collect).

Ela não lê conversas, contatos nem métricas. Mesmo assim, você define em Painel → Desenvolvedores → Widget no seu app quais domínios podem usá-la. Requisições de outros domínios são recusadas com 403 origin_not_allowed. Há uma chave pública por ambiente; gerar outra desativa a anterior na hora.

Token de sessão

Quando o usuário já está logado no seu sistema, o seu servidor gera um token de sessão e entrega ao front. Assim o widget sabe quem é a pessoa sem expor a chave secreta.

curl https://api.nevox.ai/v1/widget/sessions \
  -H "Authorization: Bearer $NEVOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agt_8f2k1x",
    "contact": {
      "external_id": "paciente_1042",
      "name": "Maria Souza",
      "email": "maria@exemplo.com",
      "language": "pt-BR"
    }
  }'

{
  "token": "nvx_st_9c1e...",
  "expires_at": "2026-11-03T15:30:00Z",
  "contact_id": "ctc_4hq81"
}

O token vale por 1 hora e serve só para aquele contato e aquele agente. Gere um novo a cada login ou quando expirar. Veja como usar no widget.

Ambientes