> ## Documentation Index > Fetch the complete documentation index at: https://docs.evolutionfoundation.com.br/llms.txt > Use this file to discover all available pages before exploring further. # Autenticação nas APIs EvoAI > Guia completo de autenticação com API Access Token (UUID) e multi-tenant para todas as APIs Evo CRM ## 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: ```http theme={null} api_access_token: ``` ### Exemplo de Uso ```bash theme={null} # A Base URL varia por ambiente curl -X GET https://api.evoai.app/api/v1/agents \ -H "api_access_token: " \ -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](../user-guides/settings/access-tokens). #### Passo a Passo Rápido 1. **Acesse as Configurações** * No menu lateral esquerdo, clique em **Settings** (Configurações) * Na lista de opções, selecione **Access Tokens** (Tokens de Acesso) 2. **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 3. **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](../user-guides/settings/access-tokens). ### 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:** ```http theme={null} api_access_token: ``` ### Métodos Alternativos por Serviço Alguns serviços podem oferecer métodos alternativos específicos: #### Evolution API * **ApiKeyAuth** - Header: `apikey` ```http theme={null} apikey: ``` > **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: ```http theme={null} # Exemplo ilustrativo - o nome do header varia por serviço X-Account-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 ```bash theme={null} # 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: " \ -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: " \ -H "X-Account-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:** ```bash theme={null} # 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: " # Se o token estiver inválido, obtenha um novo através do painel administrativo ``` **Resposta de erro:** ```json theme={null} { "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:** 1. Verifique as permissões associadas ao seu token 2. Confirme que sua conta tem as permissões necessárias 3. Verifique se está acessando recursos do tenant correto **Resposta de erro:** ```json theme={null} { "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 ```bash theme={null} #!/bin/bash # Configuração # A Base URL varia por ambiente API_URL="https://api.evoai.app/api/v1/agents" API_TOKEN="" # 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 ```javascript theme={null} // 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 ```python theme={null} 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 ```bash theme={null} # Configurar token como variável de ambiente export API_ACCESS_TOKEN="" # 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 1. **Obtenha seu API Access Token** através do painel administrativo 2. **Configure o token** em variáveis de ambiente ou configuração segura 3. **Teste a autenticação** usando os exemplos acima 4. **Consulte a documentação específica** de cada serviço para detalhes adicionais 5. **Explore as especificações OpenAPI** para ver detalhes de autenticação por endpoint ## Referências * [Introdução às APIs](./introduction) - 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. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.