Activation Flow - Documentação do Evolution Foundation

For deploys after the first registration of the same email, you can skip the browser and use auto-activation by email — a single API call. The flow below is still required for the first registration of an email.

Flow overview

Manual activation flow diagram: instance calls register/init, displays URL, operator authenticates in browser, instance polls, receives api_key, activates via HMAC and continues with heartbeats.

The base URL is set via the LICENSE_BASE_URL env var in the product .env (default: https://license.evolutionfoundation.com.br).

Step 1 — Initiate registration

When the instance detects no api_key is saved locally, it calls:

POST /v1/register/init
Content-Type: application/json

{
  "tier": "community",
  "version": "2.4.0",
  "instance_id": "550e8400-e29b-41d4-a716-446655440000"
}

Fields:

Field	Type	Description
`tier`	string	`community` or `beta`
`version`	string	Evolution product version (e.g. `2.4.0`)
`instance_id`	UUID v4	Local instance identifier — generated once and persisted

Response (200):

{
  "register_url": "https://license.evolutionfoundation.com.br/register?token=abc123def456...",
  "token": "abc123def456..."
}

The token expires in 30 minutes. Rate limit is 10 inits per hour per IP. If the operator doesn’t complete activation in time, just repeat step 1.

Possible errors:

HTTP	Code	Meaning
400	`INVALID_TIER`	tier is neither `community` nor `beta`
400	`INVALID_BODY`	malformed JSON
429	`RATE_LIMIT`	exceeded 10 inits/hour

Step 2 — Show URL to operator

The instance displays register_url to the operator. Accepted patterns:

Web UI / Manager — “Activate License” button opens the link in a browser
Terminal / CLI — print the URL and wait
QR Code — in headless deployments, generate a QR for scanning

CLI output example:

─────────────────────────────────────────────────────────────────
  Evolution API license activation
─────────────────────────────────────────────────────────────────

  To activate, open in your browser:

  https://license.evolutionfoundation.com.br/register?token=abc123def...

  Waiting for confirmation... (expires in 30 minutes)
─────────────────────────────────────────────────────────────────

Step 3 — What happens in the browser

The license server renders the registration page with Evolution’s visual identity. The operator picks one of:

Magic Link — provides name + email, receives a confirmation link by email
Google OAuth — Google account login
GitHub OAuth — GitHub account login

After authenticating, the server creates (or retrieves) the customer and generates an internal authorization_code. This flow is transparent to the instance — it only needs to poll.

Step 4 — Status polling

While the operator handles login, the instance polls:

GET /v1/register/status?token=abc123def456...

While pending:

{ "status": "pending" }

On completion:

{
  "status": "completed",
  "api_key": "64chars_hex_key...",
  "customer_id": 8,
  "tier": "community"
}

After expiration:

{ "status": "expired" }

Implementation recommendations:

Polling interval between 3 and 5 seconds (not faster)
Total timeout of 30 minutes
On completed, persist api_key in a secure location (encrypted config, secret manager, etc.)

Step 5 — Activate the instance

With the api_key in hand, the instance calls the activation endpoint:

POST /v1/activate
Content-Type: application/json
X-API-Key: 64chars_hex_key...
X-Signature: <HMAC-SHA256 of body using api_key>

{
  "instance_id": "550e8400-e29b-41d4-a716-446655440000",
  "version": "2.4.0"
}

Response:

{
  "status": "active",
  "tier": "community",
  "instance_id": "550e8400-e29b-41d4-a716-446655440000"
}

Geolocation (operator_country, operator_city) is detected automatically from the request IP. The instance does not send that info.

Step 6 — Periodic heartbeat

After activation, the instance sends heartbeats every 5 minutes:

POST /v1/heartbeat
Content-Type: application/json
X-API-Key: 64chars_hex_key...
X-Signature: <HMAC-SHA256 of body>

{
  "instance_id": "550e8400-e29b-41d4-a716-446655440000",
  "telemetry_bundle": {
    "messages_sent": 1500,
    "features": ["chatbot", "broadcast", "webhook"]
  }
}

The telemetry_bundle field is free-form JSON. Fields extracted automatically by the server are detailed in Telemetry.

Step 7 — Deactivation (optional)

On graceful shutdown (uninstall, intentional container stop), recommended:

POST /v1/deactivate
Content-Type: application/json
X-API-Key: 64chars_hex_key...
X-Signature: <HMAC-SHA256 of body>

{
  "instance_id": "550e8400-e29b-41d4-a716-446655440000"
}

This frees the instance count in licensing. Not mandatory — the server auto-expires inactive instances after 7 days without heartbeat.

HMAC authentication

All calls to /v1/activate, /v1/heartbeat and /v1/deactivate require the X-Signature header with HMAC-SHA256 of the body. Algorithm:

Serialize the body as JSON
Compute HMAC-SHA256(body, api_key)
Convert to hexadecimal
Send in the X-Signature header

The body used in the HMAC must be byte-for-byte identical to what is sent. Do not reformat the JSON between signing and sending.

Python example

import hmac, hashlib, json, requests

api_key = "64chars_hex..."
payload = {
    "instance_id": "550e8400-e29b-41d4-a716-446655440000",
    "version": "2.4.0",
}
body = json.dumps(payload, separators=(",", ":"))
sig = hmac.new(api_key.encode(), body.encode(), hashlib.sha256).hexdigest()

requests.post(
    "https://license.evolutionfoundation.com.br/v1/activate",
    data=body,
    headers={
        "Content-Type": "application/json",
        "X-API-Key": api_key,
        "X-Signature": sig,
    },
)

Node.js example

const crypto = require('crypto');

const apiKey = '64chars_hex...';
const payload = {
  instance_id: '550e8400-e29b-41d4-a716-446655440000',
  version: '2.4.0',
};
const body = JSON.stringify(payload);
const sig = crypto.createHmac('sha256', apiKey).update(body).digest('hex');

await fetch('https://license.evolutionfoundation.com.br/v1/activate', {
  method: 'POST',
  body,
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': apiKey,
    'X-Signature': sig,
  },
});

Go example

package main

import (
    "crypto/hmac"
    "crypto/sha256"
    "encoding/hex"
)

func sign(body []byte, apiKey string) string {
    mac := hmac.New(sha256.New, []byte(apiKey))
    mac.Write(body)
    return hex.EncodeToString(mac.Sum(nil))
}

Error codes

HTTP	Code	Cause	Recommended action
401	`HMAC_INVALID`	Wrong signature	Check body serialization
401	`INVALID_API_KEY`	Malformed key	Confirm use of the 64-char hex
403	`KEY_SUSPENDED`	Key suspended for abuse	Contact support
403	`INSTANCE_LIMIT`	Instance limit reached	Request limit increase
404	`INSTANCE_NOT_FOUND`	Heartbeat without prior activation	Run `/v1/activate` first
410	`TOKEN_EXPIRED`	30-min token expired	Re-run `/v1/register/init`
429	`RATE_LIMIT`	Rate limit exceeded	Exponential backoff

Integration checklist

For those implementing activation in a fork or derivative product:

Offline mode and degradation

If the license server is unreachable:

The instance keeps working normally
Heartbeats fail silently (no application crash)
After reconnection, the next heartbeat resumes the cycle

The initial activation (steps 1–5) is the only stage that requires connectivity. After that, the instance tolerates offline periods. See FAQ — offline mode for details.

​Flow overview

​Step 1 — Initiate registration

​Step 2 — Show URL to operator

​Step 3 — What happens in the browser

​Step 4 — Status polling

​Step 5 — Activate the instance

​Step 6 — Periodic heartbeat

​Step 7 — Deactivation (optional)

​HMAC authentication

​Python example

​Node.js example

​Go example

​Error codes

​Integration checklist

​Offline mode and degradation

Flow overview

Step 1 — Initiate registration

Step 2 — Show URL to operator

Step 3 — What happens in the browser

Step 4 — Status polling

Step 5 — Activate the instance

Step 6 — Periodic heartbeat

Step 7 — Deactivation (optional)

HMAC authentication

Python example

Node.js example

Go example

Error codes

Integration checklist

Offline mode and degradation