Authentication in EvoAI APIs - Documentação do Evolution Foundation

Overview

Evo CRM APIs use API Access Token (UUID) as the main authentication standard. The token is sent in the HTTP header api_access_token in all authenticated requests.

API Access Token (Main Standard)

The API Access Token is a unique identifier (UUID) that authenticates your requests to Evo CRM APIs.

Header Format

Include the token in the api_access_token header of all requests:

api_access_token: <YOUR_TOKEN_UUID>

Usage Example

# Base URL varies by environment
curl -X GET https://api.evoai.app/api/v1/agents \
  -H "api_access_token: <YOUR_TOKEN_UUID>" \
  -H "Content-Type: application/json"

Where to Get the Token

The API Access Token (UUID) can be obtained through the system’s administrative panel. For a complete guide and detailed step-by-step instructions on how to create, manage, and use access tokens, consult the Access Tokens Guide.

Quick Step-by-Step

Access Settings
- In the left sidebar menu, click Settings
- In the options list, select Access Tokens
Create a New Token
- Click the green ”+ New Token” button in the top right corner
- Fill out the form:
  - Token Name: Descriptive name to identify the token (e.g., “API Token - 2026-01-27”)
  - Permissions (Scopes): Select the necessary permissions for the token
- Click “New Token” to create
Copy and Store the Token
- After creating the token, the value will be displayed only once
- Copy the token immediately and store it in a secure location
- Use the “Copy Token” button in the actions menu to copy existing tokens

Token Management

View: Use “View Token” in the actions menu to see complete details
Edit: Use “Edit” to modify token name and permissions
Regenerate: Use “Regenerate Token” to generate a new value (invalidates the previous one)
Delete: Use “Delete” to permanently remove a token

Important:

The token value can only be viewed immediately after creation

Follow the principle of least privilege when selecting permissions

Store tokens in environment variables or secure password managers

Never share tokens publicly or in code repositories

For detailed instructions with images and complete examples, consult the Complete Access Tokens Guide.

Token Security

Never share your token publicly or in code repositories
Use environment variables to store tokens in applications
Revoke compromised tokens immediately through the administrative panel
Rotate tokens periodically as a security practice

Authentication Methods by Service

API Access Token Standard (Recommended)

Most services use API Access Token as the main method:

✅ 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 (when applicable)

Usage:

api_access_token: <YOUR_TOKEN_UUID>

Alternative Methods by Service

Some services may offer specific alternative methods:

Evolution API

ApiKeyAuth - Header: apikey

apikey: <your-api-key>

Note: For new projects, always prefer API Access Token when available. Alternative methods are maintained for compatibility with existing integrations.

Services without Defined Authentication

The following services may not have an explicit authentication scheme in the OpenAPI specification:

⚠️ Evolution Go - TODO: Verify authentication method

Consult the specific documentation for each service or contact support for authentication details.

Multi-Tenancy

The Evo CRM platform supports multi-tenancy, allowing multiple organizations (tenants) to use the same API instance in an isolated manner.

Tenant Identification

Tenant identification can be done through different mechanisms, depending on the service:

Via Token

The tenant may be associated with the API Access Token itself. In this case, the service automatically identifies the tenant from the token.

Via HTTP Header

Some services may require a specific header to identify the tenant. The header name may vary by service:

# Illustrative example - header name varies by service
X-Account-ID: <tenant-id>

Note: The example above (X-Account-ID) is only illustrative. The exact header name and identification mechanism vary by service. Consult the specific documentation for each service or check the corresponding OpenAPI specification to confirm the header used.

Data Isolation

Each tenant has:

Isolated data (contacts, conversations, agents, etc.)
Independent settings
Own limits and quotas
Specific users and permissions

Example Request with Tenant

# Tenant can be automatically identified via token
# Base URL varies by environment
curl -X GET https://api.evoai.app/api/v1/agents \
  -H "api_access_token: <YOUR_TOKEN_UUID>" \
  -H "Content-Type: application/json"

# Or explicitly via header (if supported by the service)
# Note: Header name varies by service - consult specific documentation
# Base URL varies by environment
curl -X GET https://api.evoai.app/api/v1/agents \
  -H "api_access_token: <YOUR_TOKEN_UUID>" \
  -H "X-Account-ID: <tenant-id>" \
  -H "Content-Type: application/json"

Note: Consult the specific documentation for each service to confirm the tenant identification method used. The header name may vary between services.

Common Errors

401 Unauthorized

Causes:

Missing token in api_access_token header
Invalid or malformed token
Revoked or expired token
Token does not have permission for the resource

Solution:

# Check if header is present
# Base URL varies by environment
curl -v -X GET https://api.evoai.app/api/v1/agents \
  -H "api_access_token: <YOUR_TOKEN_UUID>"

# If token is invalid, obtain a new one through the administrative panel

Error response:

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

403 Forbidden

Causes:

Valid token, but no permission for the resource
Attempting to access resource from another tenant
User without necessary role/permission

Solution:

Check permissions associated with your token
Confirm your account has the necessary permissions
Verify you are accessing resources from the correct tenant

Error response:

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

Practical Examples

Example 1: Basic Request with API Access Token

#!/bin/bash

# Configuration
# Base URL varies by environment
API_URL="https://api.evoai.app/api/v1/agents"
API_TOKEN="<YOUR_TOKEN_UUID>"

# Make request
curl -X GET "$API_URL" \
  -H "api_access_token: $API_TOKEN" \
  -H "Content-Type: application/json" | jq .

Example 2: Request with Error Handling

// Example in JavaScript/Node.js
async function makeAuthenticatedRequest(url, options = {}) {
  const API_TOKEN = process.env.API_ACCESS_TOKEN;
  
  if (!API_TOKEN) {
    throw new Error('API_ACCESS_TOKEN not configured');
  }
  
  // Make request
  const response = await fetch(url, {
    ...options,
    headers: {
      'api_access_token': API_TOKEN,
      'Content-Type': 'application/json',
      ...options.headers
    }
  });
  
  // Handle authentication errors
  if (response.status === 401) {
    throw new Error('Invalid or missing token. Check your API Access Token.');
  }
  
  if (response.status === 403) {
    throw new Error('No permission to access this resource');
  }
  
  return response;
}

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

Example 3: Python with 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):
        """Makes authenticated request with 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('Invalid or missing token. Check your API Access Token.')
        
        if response.status_code == 403:
            raise Exception('No permission to access this resource')
        
        response.raise_for_status()
        return response

# Usage
# Base URL varies by environment
client = EvoAIClient(
    api_token=os.getenv('API_ACCESS_TOKEN'),
    api_url='https://api.evoai.app/api/v1'
)

# Make request
response = client.request('GET', '/agents')
print(response.json())

Example 4: Using Environment Variables

# Set token as environment variable
export API_ACCESS_TOKEN="<YOUR_TOKEN_UUID>"

# Use in requests
# Base URL varies by environment
curl -X GET https://api.evoai.app/api/v1/agents \
  -H "api_access_token: $API_ACCESS_TOKEN" \
  -H "Content-Type: application/json"

Next Steps

Obtain your API Access Token through the administrative panel
Configure the token in environment variables or secure configuration
Test authentication using the examples above
Consult specific documentation for each service for additional details
Explore OpenAPI specifications to see authentication details per endpoint

References

Introduction to APIs - Overview of EvoAI APIs
OpenAPI specifications for each service - Complete endpoint documentation

Need help? Consult the specific documentation for each service or contact support.

​Overview

​API Access Token (Main Standard)

​Header Format

​Usage Example

​Where to Get the Token

​Quick Step-by-Step

​Token Management

​Token Security

​Authentication Methods by Service

​API Access Token Standard (Recommended)

​Alternative Methods by Service

​Evolution API

​Services without Defined Authentication

​Multi-Tenancy

​Tenant Identification

​Via Token

​Via HTTP Header

​Data Isolation

​Example Request with Tenant

​Common Errors

​401 Unauthorized

​403 Forbidden

​Practical Examples

​Example 1: Basic Request with API Access Token

​Example 2: Request with Error Handling

​Example 3: Python with API Access Token

​Example 4: Using Environment Variables

​Next Steps

​References