Autenticação

Toda chamada à API leva a chave no cabeçalho Authorization:

Authorization: Bearer cvk_...

Sem o cabeçalho, ou com uma chave inexistente, revogada ou vencida, a resposta é 401 invalid_api_key.

O que a chave define

A chave identifica o cliente da Cavori, a integração e os agentes que a integração pode usar. Nenhum cabeçalho ou campo do corpo muda esse escopo. Chamar um agente que a integração não pode usar responde 404 not_found, o mesmo erro de um agente que não existe.

Uma conversa pertence à integração que a abriu. Outra integração, mesmo do mesmo cliente, não enxerga essa conversa e recebe 404 not_found.

Emitir a chave

No portal da Cavori, em Configurações → Integrações, abra a integração e emita uma chave. O valor completo aparece só na emissão. Depois disso a Cavori guarda apenas um hash e mostra só o prefixo, então uma chave perdida não pode ser recuperada: emita outra.

A chave dá acesso aos agentes do cliente e gera cobrança na carteira dele. Trate-a como uma senha:

• guarde em um cofre de segredos ou em variável de ambiente do servidor;
• nunca coloque em código de navegador, app mobile, repositório ou log (veja Sites);
• use uma chave por ambiente, para poder revogar uma sem afetar a outra.

Rotacionar

Uma integração pode ter várias chaves ao mesmo tempo, e trocar a chave não altera as conversas existentes. Para rotacionar sem interrupção:

1. Emita uma chave nova na mesma integração.
2. Publique o seu servidor com a chave nova.
3. Confirme que o tráfego passou para a nova.
4. Revogue a chave antiga.

Revogar

Em Configurações → Integrações, revogue a chave. A partir daí, as chamadas com ela respondem 401 invalid_api_key. A revogação não apaga conversas nem mensagens. Para cortar o acesso de uma integração inteira, revogue todas as chaves dela.

Webhooks usam outro segredo

O segredo do webhook é diferente da chave cvk_.... A chave autentica as suas chamadas à Cavori; o segredo do webhook serve para você verificar que as chamadas que chegam ao seu servidor vêm da Cavori.