Autenticação

A API do Menthor utiliza chaves de API para garantir a segurança dos endpoints. Todas as requisições devem incluir uma chave válida no cabeçalho (Header) da mensagem.

Configuração do Header

Para interagir com o serviço, adicione o seguinte campo ao header da requisição HTTP:

X-API-Key: sua_chave_aqui

Exemplo com cURL

Abaixo, um exemplo de como realizar o «ping» na API utilizando a autenticação via terminal:

curl -X GET http://localhost:8000/ping \
     -H "X-API-Key: sua_chave_aqui"

Erros de Autenticação

Se a chave estiver ausente ou for inválida, a API retornará os seguintes códigos:

  • 403 Forbidden: A chave de API não foi fornecida ou não tem permissão para aceder ao recurso.

  • 401 Unauthorized: A chave fornecida expirou ou é inválida para este ambiente.

Dica

As chaves de API são configuradas no arquivo .env do servidor. Se precisar de uma nova chave ou de acesso para um novo desenvolvedor, contate o administrador do sistema.

Autenticação de Usuário Final (OTP via E-mail)

Enquanto o cabeçalho X-API-Key valida o acesso da aplicação cliente à API (comunicação máquina-para-máquina), os fluxos de mensagens interativas (/token_streaming, /sentence_streaming e /block_streaming) realizam a validação de identidade do usuário final.

Quando um usuário envia mensagens a partir de um canal de mensageria (como o WhatsApp) com um identificador de canal (wpp_lid) que ainda não esteja associado a um cadastro existente:

  1. A API interrompe o processamento do prompt e solicita que o usuário forneça seu e-mail cadastrado.

  2. O sistema localiza o cadastro, gera um código numérico de uso único (OTP de 6 dígitos) e o envia para o e-mail corporativo do usuário via SMTP.

  3. O código possui validade de 5 minutos (gerenciada no Redis) e limite de 3 tentativas incorretas.

  4. Assim que o usuário responde com o código correto, o wpp_lid é automaticamente vinculado à sua conta, permitindo que todas as próximas mensagens sejam autorizadas de forma transparente.

Para detalhes sobre o ciclo de vida deste processo, consulte Usuários e Históricos.