Authentication

Authentication

Evolution API Lite uses a dual-layer API key authentication system to secure access to the API endpoints. This system provides both global administrative access and instance-specific access control.

Authentication Overview

The API implements two types of authentication keys:

1. Global API Key: Administrative access for creating instances and managing the system
2. Instance Token: Instance-specific access for operations on individual WhatsApp connections

Global API Key

Configuration

The global API key is configured via the AUTHENTICATION_API_KEY environment variable:

# Define a global apikey to access all instances
AUTHENTICATION_API_KEY=429683C4C977415CAAFCCE10F7D57E11

Usage

The global API key must be included in the request headers for:

• Creating new instances (/instance/create)
• Fetching all instances (/instance/fetchInstances)
• Administrative operations

Header Format:

apikey: 429683C4C977415CAAFCCE10F7D57E11

Example Request

curl -X POST http://localhost:8080/instance/create \
  -H "Content-Type: application/json" \
  -H "apikey: 429683C4C977415CAAFCCE10F7D57E11" \
  -d '{
    "instanceName": "my-instance",
    "integration": "WHATSAPP-BAILEYS"
  }'

Instance Token

How Instance Tokens Work

When you create a new instance, the system automatically generates a unique token for that instance. This token provides access to all operations specific to that instance.

Token Generation

Instance tokens are automatically generated during instance creation and stored in the database. Each instance has its own unique token that cannot be changed after creation.

Usage

Instance tokens are used for all instance-specific operations:

• Sending messages
• Managing contacts and chats
• Group operations
• Instance settings and configuration

Header Format:

apikey: <instance-token>

Finding Your Instance Token

You can retrieve your instance token by:

1. During Creation: The token is returned in the instance creation response
2. Fetch Instances: Use the global API key to fetch all instances and their tokens

# Fetch all instances with their tokens
curl -X GET http://localhost:8080/instance/fetchInstances \
  -H "apikey: 429683C4C977415CAAFCCE10F7D57E11"

Example Instance Operation

curl -X POST http://localhost:8080/message/sendText/my-instance \
  -H "Content-Type: application/json" \
  -H "apikey: <instance-token>" \
  -d '{
    "number": "5511999999999",
    "text": "Hello from Evolution API!"
  }'

Authentication Flow

1. Instance Creation Flow

sequenceDiagram
participant Client
participant API
participant Database

Client->>API: POST /instance/create (Global API Key)
API->>API: Validate Global API Key
API->>Database: Create Instance Record
API->>Database: Generate & Store Instance Token
API->>Client: Return Instance Details + Token

2. Instance Operation Flow

sequenceDiagram
participant Client
participant API
participant Database

Client->>API: POST /message/sendText/:instance (Instance Token)
API->>Database: Validate Instance Token
API->>API: Execute Operation
API->>Client: Return Operation Result

Authentication Guard Implementation

The authentication system is implemented in the auth.guard.ts file with the following logic:

Validation Priority

1. Global API Key Check: First checks if the provided key matches the global API key
2. Instance Token Check: If not global, validates against instance-specific tokens
3. Context-Aware Validation: Different validation rules for different endpoints

Special Cases

• Instance Creation: Requires global API key
• Fetch Instances: Accepts either global API key or valid instance token
• Instance Operations: Requires matching instance token

Configuration Options

Expose Instances

Control whether instance tokens are exposed in the fetch instances endpoint:

# If true, instance tokens are included in fetch instances response
AUTHENTICATION_EXPOSE_IN_FETCH_INSTANCES=true

When set to false, instance tokens are hidden from the fetch instances response for security.

Security Best Practices

Global API Key Security

Caution

The global API key provides administrative access to your entire Evolution API installation. Keep it secure and never expose it in client-side code.

• Store the global API key securely (environment variables, secrets management)
• Use different keys for different environments (development, staging, production)
• Rotate keys periodically
• Monitor access logs for unauthorized usage

Instance Token Security

• Instance tokens are automatically generated and cannot be changed
• Each instance has a unique token
• Tokens are stored securely in the database
• Use HTTPS in production to protect tokens in transit

Network Security

• Always use HTTPS in production environments
• Consider implementing rate limiting
• Use proxy configurations when needed for additional security layers
• Monitor authentication failures and implement alerting

Error Responses

Unauthorized (401)

Returned when no API key is provided or the key is invalid:

{
  "status": 401,
  "error": "Unauthorized",
  "response": {
    "message": "Unauthorized access"
  }
}

Forbidden (403)

Returned when the API key doesn’t have permission for the requested operation:

{
  "status": 403,
  "error": "Forbidden",
  "response": {
    "message": "Missing global api key"
  }
}

Troubleshooting

Common Issues

1. “Unauthorized” Error: Check that you’re including the apikey header
2. “Forbidden” Error: Ensure you’re using the correct key type (global vs instance)
3. Instance Not Found: Verify the instance name and token combination
4. Token Mismatch: Ensure you’re using the correct instance token for the specific instance

Debugging Tips

• Enable debug logging to see authentication attempts
• Verify your environment variables are loaded correctly
• Check database connectivity if instance token validation fails
• Ensure your HTTP client is sending headers correctly

This dual-layer authentication system provides both security and flexibility, allowing you to manage multiple WhatsApp instances while maintaining proper access control.