Autenticação

Toda requisição à API da EvoluAI 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

Ambos os headers devem estar presentes em todas as requisições. A ausência de qualquer um retorna 401 Unauthorized.

Como obter sua API Key

Acesse o Dashboard da EvoluAI
Vá em Configurações → API Keys
Clique em Nova Chave
Defina um nome descritivo (ex: Integração CRM, Script ETL)
Selecione as permissões necessárias
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

Use o endpoint user.me para confirmar que sua API Key está válida e ativa:

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

Resposta esperada:

{
  "result": {
    "data": {
      "id": "user_123",
      "name": "Maria Silva",
      "email": "maria@empresa.com",
      "role": "admin_company",
      "companyId": "comp_456"
    }
  }
}

Permissões e papéis

A API Key herda as permissões do usuário que a criou. O nível de acesso depende do papel (role):

Papel	Acesso
`salesperson`	Apenas suas próprias análises
`supervisor`	Análises dos vendedores supervisionados
`admin_company`	Todos os dados da empresa, gestão de usuários e API Keys
`super_admin`	Acesso irrestrito a todas as empresas (uso interno)

Para integrações de sistema (ETL, CRM, automações), crie a API Key com um usuário admin_company — isso garante acesso completo aos dados da empresa sem depender de um usuário específico.

Limite de API Keys

Cada empresa pode ter no máximo 10 API Keys ativas simultaneamente. Ao atingir o limite, revogue chaves não utilizadas antes de criar novas.

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 via API

Você também pode gerenciar suas chaves programaticamente:

Listar chaves ativas

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

Resposta:

{
  "result": {
    "data": [
      {
        "id": "key_abc",
        "name": "Integração CRM",
        "createdAt": "2025-01-01T00:00:00Z",
        "lastUsedAt": "2025-01-15T10:22:00Z",
        "expiresAt": null
      }
    ]
  }
}

Criar nova chave

curl -X POST 'https://api.evolu-ai.com/trpc/apiKeys.create' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: evai_your_key_here' \
  -d '{
    "json": {
      "name": "Script de ETL",
      "expiresAt": "2025-12-31T23:59:59Z"
    }
  }'

Revogar chave

curl -X POST 'https://api.evolu-ai.com/trpc/apiKeys.revoke' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: evai_your_key_here' \
  -d '{
    "json": {
      "keyId": "key_abc"
    }
  }'

A revogação é imediata e irreversível. Requisições em andamento usando a chave revogada irão falhar com 401 Unauthorized.

Autenticação

On this page