Autenticação nas APIs EvoAI - Documentação do Evolution Foundation

Visão Geral

As APIs Evo CRM utilizam API Access Token (UUID) como padrão principal de autenticação. O token é enviado no header HTTP api_access_token em todas as requisições autenticadas.

API Access Token (Padrão Principal)

O API Access Token é um identificador único (UUID) que autentica suas requisições às APIs Evo CRM.

Formato do Header

Inclua o token no header api_access_token de todas as requisições:

api_access_token: <SEU_TOKEN_UUID>

Exemplo de Uso

# A Base URL varia por ambiente
curl -X GET https://api.evoai.app/api/v1/agents \
  -H "api_access_token: <SEU_TOKEN_UUID>" \
  -H "Content-Type: application/json"

Onde Obter o Token

O API Access Token (UUID) pode ser obtido através do painel administrativo do sistema. Para um guia completo e passo a passo detalhado sobre como criar, gerenciar e usar tokens de acesso, consulte o Guia de Tokens de Acesso.

Passo a Passo Rápido

Acesse as Configurações
- No menu lateral esquerdo, clique em Settings (Configurações)
- Na lista de opções, selecione Access Tokens (Tokens de Acesso)
Crie um Novo Token
- Clique no botão verde ”+ New Token” no canto superior direito
- Preencha o formulário:
  - Token Name: Nome descritivo para identificar o token (ex: “API Token - 2026-01-27”)
  - Permissions (Scopes): Selecione as permissões necessárias para o token
- Clique em “New Token” para criar
Copie e Armazene o Token
- Após criar o token, o valor será exibido uma única vez
- Copie o token imediatamente e armazene em local seguro
- Use o botão “Copy Token” no menu de ações para copiar tokens existentes

Gerenciamento de Tokens

Visualizar: Use “View Token” no menu de ações para ver detalhes completos
Editar: Use “Edit” para modificar nome e permissões do token
Regenerar: Use “Regenerate Token” para gerar um novo valor (invalida o anterior)
Excluir: Use “Delete” para remover permanentemente um token

Importante:

O valor do token só pode ser visualizado imediatamente após a criação

Siga o princípio do menor privilégio ao selecionar permissões

Armazene tokens em variáveis de ambiente ou gerenciadores de senhas seguros

Nunca compartilhe tokens publicamente ou em repositórios de código

Para instruções detalhadas com imagens e exemplos completos, consulte o Guia Completo de Tokens de Acesso.

Segurança do Token

Nunca compartilhe seu token publicamente ou em repositórios de código
Use variáveis de ambiente para armazenar tokens em aplicações
Revogue tokens comprometidos imediatamente através do painel administrativo
Rotacione tokens periodicamente como prática de segurança

Métodos de Autenticação por Serviço

Padrão API Access Token (Recomendado)

A maioria dos serviços utiliza API Access Token como método principal:

✅ EvoAI Core Service - api_access_token
✅ EvoAI CRM - api_access_token
✅ EvoAI Campaign - api_access_token
✅ EvoAI Processor - api_access_token
✅ EvoAI Knowledge - api_access_token (quando aplicável)

Uso:

api_access_token: <SEU_TOKEN_UUID>

Métodos Alternativos por Serviço

Alguns serviços podem oferecer métodos alternativos específicos:

Evolution API

ApiKeyAuth - Header: apikey

apikey: <sua-api-key>

Nota: Para novos projetos, prefira sempre API Access Token quando disponível. Os métodos alternativos são mantidos para compatibilidade com integrações existentes.

Serviços sem Autenticação Definida

Os seguintes serviços podem não possuir esquema de autenticação explícito na especificação OpenAPI:

⚠️ Evolution Go - TODO: Verificar método de autenticação

Consulte a documentação específica de cada serviço ou entre em contato com o suporte para detalhes de autenticação.

Multi-Tenancy

A plataforma Evo CRM suporta multi-tenancy, permitindo que múltiplas organizações (tenants) utilizem a mesma instância da API de forma isolada.

Identificação do Tenant

A identificação do tenant pode ser feita através de diferentes mecanismos, dependendo do serviço:

Via Token

O tenant pode estar associado ao próprio API Access Token. Neste caso, o serviço identifica automaticamente o tenant a partir do token.

Via Header HTTP

Alguns serviços podem exigir um header específico para identificar o tenant. O nome do header pode variar por serviço:

# Exemplo ilustrativo - o nome do header varia por serviço
X-Account-ID: <tenant-id>

Nota: O exemplo acima (X-Account-ID) é apenas ilustrativo. O nome exato do header e o mecanismo de identificação variam por serviço. Consulte a documentação específica de cada serviço ou verifique a especificação OpenAPI correspondente para confirmar o header utilizado.

Isolamento de Dados

Cada tenant possui:

Dados isolados (contatos, conversas, agentes, etc.)
Configurações independentes
Limites e quotas próprios
Usuários e permissões específicos

Exemplo de Requisição com Tenant

# O tenant pode ser identificado automaticamente via token
# A Base URL varia por ambiente
curl -X GET https://api.evoai.app/api/v1/agents \
  -H "api_access_token: <SEU_TOKEN_UUID>" \
  -H "Content-Type: application/json"

# Ou explicitamente via header (se suportado pelo serviço)
# Nota: O nome do header varia por serviço - consulte a documentação específica
# A Base URL varia por ambiente
curl -X GET https://api.evoai.app/api/v1/agents \
  -H "api_access_token: <SEU_TOKEN_UUID>" \
  -H "X-Account-ID: <tenant-id>" \
  -H "Content-Type: application/json"

Nota: Consulte a documentação específica de cada serviço para confirmar o método de identificação de tenant utilizado. O nome do header pode variar entre serviços.

Erros Comuns

401 Unauthorized

Causas:

Token ausente no header api_access_token
Token inválido ou malformado
Token revogado ou expirado
Token não possui permissão para o recurso

Solução:

# Verificar se o header está presente
# A Base URL varia por ambiente
curl -v -X GET https://api.evoai.app/api/v1/agents \
  -H "api_access_token: <SEU_TOKEN_UUID>"

# Se o token estiver inválido, obtenha um novo através do painel administrativo

Resposta de erro:

{
  "error": "Unauthorized",
  "message": "Invalid or missing authentication token",
  "code": "ERR_UNAUTHORIZED"
}

403 Forbidden

Causas:

Token válido, mas sem permissão para o recurso
Tentativa de acessar recurso de outro tenant
Usuário sem role/permissão necessária

Solução:

Verifique as permissões associadas ao seu token
Confirme que sua conta tem as permissões necessárias
Verifique se está acessando recursos do tenant correto

Resposta de erro:

{
  "error": "Forbidden",
  "message": "You don't have permission to access this resource",
  "code": "ERR_FORBIDDEN"
}

Exemplos Práticos

Exemplo 1: Requisição Básica com API Access Token

#!/bin/bash

# Configuração
# A Base URL varia por ambiente
API_URL="https://api.evoai.app/api/v1/agents"
API_TOKEN="<SEU_TOKEN_UUID>"

# Fazer requisição
curl -X GET "$API_URL" \
  -H "api_access_token: $API_TOKEN" \
  -H "Content-Type: application/json" | jq .

Exemplo 2: Requisição com Tratamento de Erros

// Exemplo em JavaScript/Node.js
async function fazerRequisicaoAutenticada(url, options = {}) {
  const API_TOKEN = process.env.API_ACCESS_TOKEN;
  
  if (!API_TOKEN) {
    throw new Error('API_ACCESS_TOKEN não configurado');
  }
  
  // Fazer requisição
  const response = await fetch(url, {
    ...options,
    headers: {
      'api_access_token': API_TOKEN,
      'Content-Type': 'application/json',
      ...options.headers
    }
  });
  
  // Tratar erros de autenticação
  if (response.status === 401) {
    throw new Error('Token inválido ou ausente. Verifique seu API Access Token.');
  }
  
  if (response.status === 403) {
    throw new Error('Sem permissão para acessar este recurso');
  }
  
  return response;
}

// Uso
const response = await fazerRequisicaoAutenticada('https://api.evoai.app/api/v1/agents');
const data = await response.json();
console.log(data);

Exemplo 3: Python com API Access Token

import os
import requests

class EvoAIClient:
    def __init__(self, api_token, api_url):
        self.api_token = api_token
        self.api_url = api_url
    
    def request(self, method, endpoint, **kwargs):
        """Faz requisição autenticada com API Access Token"""
        url = f"{self.api_url}{endpoint}"
        
        headers = kwargs.get('headers', {})
        headers['api_access_token'] = self.api_token
        headers['Content-Type'] = 'application/json'
        kwargs['headers'] = headers
        
        response = requests.request(method, url, **kwargs)
        
        if response.status_code == 401:
            raise Exception('Token inválido ou ausente. Verifique seu API Access Token.')
        
        if response.status_code == 403:
            raise Exception('Sem permissão para acessar este recurso')
        
        response.raise_for_status()
        return response

# Uso
# A Base URL varia por ambiente
client = EvoAIClient(
    api_token=os.getenv('API_ACCESS_TOKEN'),
    api_url='https://api.evoai.app/api/v1'
)

# Fazer requisição
response = client.request('GET', '/agents')
print(response.json())

Exemplo 4: Usando Variáveis de Ambiente

# Configurar token como variável de ambiente
export API_ACCESS_TOKEN="<SEU_TOKEN_UUID>"

# Usar em requisições
# A Base URL varia por ambiente
curl -X GET https://api.evoai.app/api/v1/agents \
  -H "api_access_token: $API_ACCESS_TOKEN" \
  -H "Content-Type: application/json"

Próximos Passos

Obtenha seu API Access Token através do painel administrativo
Configure o token em variáveis de ambiente ou configuração segura
Teste a autenticação usando os exemplos acima
Consulte a documentação específica de cada serviço para detalhes adicionais
Explore as especificações OpenAPI para ver detalhes de autenticação por endpoint

Referências

Introdução às APIs - Visão geral das APIs EvoAI
Especificações OpenAPI de cada serviço - Documentação completa dos endpoints

Precisa de ajuda? Consulte a documentação específica de cada serviço ou entre em contato com o suporte.

​Visão Geral

​API Access Token (Padrão Principal)

​Formato do Header

​Exemplo de Uso

​Onde Obter o Token

​Passo a Passo Rápido

​Gerenciamento de Tokens

​Segurança do Token

​Métodos de Autenticação por Serviço

​Padrão API Access Token (Recomendado)

​Métodos Alternativos por Serviço

​Evolution API

​Serviços sem Autenticação Definida

​Multi-Tenancy

​Identificação do Tenant

​Via Token

​Via Header HTTP

​Isolamento de Dados

​Exemplo de Requisição com Tenant

​Erros Comuns

​401 Unauthorized

​403 Forbidden

​Exemplos Práticos

​Exemplo 1: Requisição Básica com API Access Token

​Exemplo 2: Requisição com Tratamento de Erros

​Exemplo 3: Python com API Access Token

​Exemplo 4: Usando Variáveis de Ambiente

​Próximos Passos

​Referências