Autenticación en las APIs EvoAI

​

Visión General

​

API Access Token (Estándar Principal)

​

Formato del Header

api_access_token: <TU_TOKEN_UUID>

​

Ejemplo de Uso

# La Base URL varía por entorno
curl -X GET https://api.evoai.app/api/v1/agents \
  -H "api_access_token: <TU_TOKEN_UUID>" \
  -H "Content-Type: application/json"

​

Dónde Obtener el Token

​

Paso a Paso Rápido

1. Accede a las Configuraciones
   • En el menú lateral izquierdo, haz clic en Settings (Configuraciones)
   • En la lista de opciones, selecciona Access Tokens (Tokens de Acceso)
2. Crea un Nuevo Token
   • Haz clic en el botón verde ”+ New Token” en la esquina superior derecha
   • Completa el formulario:
     • Token Name: Nombre descriptivo para identificar el token (ej: “API Token - 2026-01-27”)
     • Permissions (Scopes): Selecciona los permisos necesarios para el token
   • Haz clic en “New Token” para crear
3. Copia y Almacena el Token
   • Después de crear el token, el valor será mostrado una única vez
   • Copia el token inmediatamente y almacénalo en un lugar seguro
   • Usa el botón “Copy Token” en el menú de acciones para copiar tokens existentes

​

Gestión de Tokens

• Visualizar: Usa “View Token” en el menú de acciones para ver detalles completos
• Editar: Usa “Edit” para modificar nombre y permisos del token
• Regenerar: Usa “Regenerate Token” para generar un nuevo valor (invalida el anterior)
• Eliminar: Usa “Delete” para eliminar permanentemente un token

Importante:

• El valor del token solo puede ser visualizado inmediatamente después de la creación
• Sigue el principio del menor privilegio al seleccionar permisos
• Almacena tokens en variables de entorno o gestores de contraseñas seguros
• Nunca compartas tokens públicamente o en repositorios de código

​

Seguridad del Token

• Nunca compartas tu token públicamente o en repositorios de código
• Usa variables de entorno para almacenar tokens en aplicaciones
• Revoca tokens comprometidos inmediatamente a través del panel administrativo
• Rota tokens periódicamente como práctica de seguridad

​

Métodos de Autenticación por Servicio

​

Estándar API Access Token (Recomendado)

• ✅ 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 (cuando aplicable)

api_access_token: <TU_TOKEN_UUID>

​

Métodos Alternativos por Servicio

​

Evolution API

• ApiKeyAuth - Header: apikey

apikey: <tu-api-key>

Nota: Para nuevos proyectos, prefiere siempre API Access Token cuando esté disponible. Los métodos alternativos se mantienen para compatibilidad con integraciones existentes.

​

Servicios sin Autenticación Definida

• ⚠️ Evolution Go - TODO: Verificar método de autenticación

​

Multi-Tenancy

​

Identificación del Tenant

​

Vía Token

​

Vía Header HTTP

# Ejemplo ilustrativo - el nombre del header varía por servicio
X-Account-ID: <tenant-id>

Nota: El ejemplo arriba (X-Account-ID) es solo ilustrativo. El nombre exacto del header y el mecanismo de identificación varían por servicio. Consulta la documentación específica de cada servicio o verifica la especificación OpenAPI correspondiente para confirmar el header utilizado.

​

Aislamiento de Datos

• Datos aislados (contactos, conversaciones, agentes, etc.)
• Configuraciones independientes
• Límites y cuotas propias
• Usuarios y permisos específicos

​

Ejemplo de Solicitud con Tenant

# El tenant puede ser identificado automáticamente vía token
# La Base URL varía por entorno
curl -X GET https://api.evoai.app/api/v1/agents \
  -H "api_access_token: <TU_TOKEN_UUID>" \
  -H "Content-Type: application/json"

# O explícitamente vía header (si soportado por el servicio)
# Nota: El nombre del header varía por servicio - consulta la documentación específica
# La Base URL varía por entorno
curl -X GET https://api.evoai.app/api/v1/agents \
  -H "api_access_token: <TU_TOKEN_UUID>" \
  -H "X-Account-ID: <tenant-id>" \
  -H "Content-Type: application/json"

Nota: Consulta la documentación específica de cada servicio para confirmar el método de identificación de tenant utilizado. El nombre del header puede variar entre servicios.

​

Errores Comunes

​

401 Unauthorized

• Token ausente en el header api_access_token
• Token inválido o malformado
• Token revocado o expirado
• Token no posee permiso para el recurso

# Verificar si el header está presente
# La Base URL varía por entorno
curl -v -X GET https://api.evoai.app/api/v1/agents \
  -H "api_access_token: <TU_TOKEN_UUID>"

# Si el token está inválido, obtén uno nuevo a través del panel administrativo

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

​

403 Forbidden

• Token válido, pero sin permiso para el recurso
• Intento de acceder a recurso de otro tenant
• Usuario sin role/permiso necesaria

1. Verifica los permisos asociados a tu token
2. Confirma que tu cuenta tiene los permisos necesarios
3. Verifica si estás accediendo a recursos del tenant correcto

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

​

Ejemplos Prácticos

​

Ejemplo 1: Solicitud Básica con API Access Token

#!/bin/bash

# Configuración
# La Base URL varía por entorno
API_URL="https://api.evoai.app/api/v1/agents"
API_TOKEN="<TU_TOKEN_UUID>"

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

​

Ejemplo 2: Solicitud con Manejo de Errores

// Ejemplo en JavaScript/Node.js
async function hacerSolicitudAutenticada(url, options = {}) {
  const API_TOKEN = process.env.API_ACCESS_TOKEN;
  
  if (!API_TOKEN) {
    throw new Error('API_ACCESS_TOKEN no configurado');
  }
  
  // Hacer solicitud
  const response = await fetch(url, {
    ...options,
    headers: {
      'api_access_token': API_TOKEN,
      'Content-Type': 'application/json',
      ...options.headers
    }
  });
  
  // Manejar errores de autenticación
  if (response.status === 401) {
    throw new Error('Token inválido o ausente. Verifica tu API Access Token.');
  }
  
  if (response.status === 403) {
    throw new Error('Sin permiso para acceder a este recurso');
  }
  
  return response;
}

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

​

Ejemplo 3: Python con 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):
        """Hace solicitud autenticada con 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 o ausente. Verifica tu API Access Token.')
        
        if response.status_code == 403:
            raise Exception('Sin permiso para acceder a este recurso')
        
        response.raise_for_status()
        return response

# Uso
# La Base URL varía por entorno
client = EvoAIClient(
    api_token=os.getenv('API_ACCESS_TOKEN'),
    api_url='https://api.evoai.app/api/v1'
)

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

​

Ejemplo 4: Usando Variables de Entorno

# Configurar token como variable de entorno
export API_ACCESS_TOKEN="<TU_TOKEN_UUID>"

# Usar en solicitudes
# La Base URL varía por entorno
curl -X GET https://api.evoai.app/api/v1/agents \
  -H "api_access_token: $API_ACCESS_TOKEN" \
  -H "Content-Type: application/json"

​

Próximos Pasos

1. Obtén tu API Access Token a través del panel administrativo
2. Configura el token en variables de entorno o configuración segura
3. Prueba la autenticación usando los ejemplos arriba
4. Consulta la documentación específica de cada servicio para detalles adicionales
5. Explora las especificaciones OpenAPI para ver detalles de autenticación por endpoint

​

Referencias

• Introducción a las APIs - Visión general de las APIs EvoAI
• Especificaciones OpenAPI de cada servicio - Documentación completa de los endpoints