Auto-Activation by Email - Documentação do Evolution Foundation

When to use

The standard activation flow requires the operator to open a browser, log in (Magic Link or OAuth) and wait for the registration to complete. For the first registration of an email, that is required. For every subsequent install by the same operator (same email), you can skip the browser entirely and activate the license in a single HTTP call. Ideal for:

Automated deploys (CI/CD, Terraform, Ansible)
Multiple instances of the same product across servers
Ephemeral containers that spin up and down frequently
Programmatic provisioning (multi-tenant, multi-region)

The first activation still has to go through the manual flow (browser + Magic Link/OAuth). Only after that the email becomes “known” to the licensing server, and auto-activation starts working.

Endpoint

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

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

Fields:

Field	Type	Required	Description
`email`	string	yes	Email of a customer already registered previously
`tier`	string	yes	Product slug (`community`, `beta`, etc.)
`version`	string	yes	Product version being activated
`instance_id`	UUID v4	yes	Locally-generated UUID, same convention as `/v1/register/init`
`country`	string	no	Country override (default: server GeoIP)
`city`	string	no	City override (default: server GeoIP)

Success response (200):

{
  "status": "active",
  "api_key": "64chars_hex_key...",
  "customer_id": 8,
  "tier": "community",
  "instance_id": "550e8400-e29b-41d4-a716-446655440000"
}

The returned api_key is ready to use immediately — there is no need to call /v1/activate afterward. The instance is already active server-side. If the call is repeated with the same (email, instance_id), the response includes "reused": true and returns the same api_key from the previous call. This makes the call idempotent — safe for retry in boot scripts.

Trust model

The licensing server accepts the call using only the email as proof of identity. No second factor, no captcha, no rate limit. Why:

The email was verified once (in the initial manual registration via Magic Link or OAuth)
Issuing a license to a customer is not a destructive action — all instances stay visible in the customer portal
The customer can revoke api_keys at any moment if they detect unauthorized use
The customer can disable auto-activation (auto_activation_enabled = false) in the portal if they suspect the email leaked

Implication: anyone who knows a customer’s email can issue licenses in that name. If that is a problem for your scenario (commercial multi-tenant, shared email, suspected leak), disable auto-activation in the portal and force all deploys through the manual flow.

Error codes

HTTP	Code	When	How to handle
400	`INVALID_BODY`	Malformed JSON	Check request body
400	`MISSING_FIELD`	`email` field missing	Include the field
400	`INVALID_EMAIL`	Malformed email	Validate before sending
400	`INVALID_TIER`	`tier` does not match any product	Check the slug
400	`INVALID_INSTANCE_ID`	`instance_id` is not a UUID	Generate UUID v4
404	`CUSTOMER_NOT_FOUND`	Email has no prior registration	Fall back to the manual flow `/v1/register/init`
403	`CUSTOMER_BLOCKED`	Customer blocked or key suspended	Contact support
403	`AUTO_ACTIVATION_DISABLED`	Customer disabled auto-activation	Use manual flow
403	`INSTANCE_LIMIT`	Customer instance cap reached	Request a higher cap
409	`INSTANCE_EXISTS`	`instance_id` already exists under another customer	Generate a new UUID

The CUSTOMER_NOT_FOUND response is the canonical signal for the client to fall back to the manual flow. Always implement that fallback — a brand-new email needs to go through the manual flow first.

Recommended client flow

import os, uuid, requests

LICENSE_URL = "https://license.evolutionfoundation.com.br"

def ensure_api_key():
    if local_api_key_exists():
        return load_api_key()

    instance_id = read_or_create_instance_uuid()
    email = os.environ.get("EVOLUTION_OPERATOR_EMAIL")

    # 1. Try auto-activation if we have the email
    if email:
        resp = requests.post(f"{LICENSE_URL}/v1/register/auto", json={
            "email": email,
            "tier": "community",
            "version": PRODUCT_VERSION,
            "instance_id": instance_id,
        })
        if resp.status_code == 200:
            data = resp.json()
            save_api_key(data["api_key"])
            return data["api_key"]

        if resp.json().get("code") == "CUSTOMER_NOT_FOUND":
            pass  # fall through to manual flow below
        elif resp.status_code in (403, 409):
            raise RuntimeError(f"Auto-activation rejected: {resp.json()}")

    # 2. Fallback: manual flow with browser
    init_resp = requests.post(f"{LICENSE_URL}/v1/register/init", json={
        "tier": "community",
        "version": PRODUCT_VERSION,
        "instance_id": instance_id,
    }).json()
    print(f"Open in your browser: {init_resp['register_url']}")
    api_key = poll_until_completed(init_resp["token"])
    save_api_key(api_key)
    return api_key

Standard env var

Evolution products read the operator email from the EVOLUTION_OPERATOR_EMAIL env var:

# .env
EVOLUTION_OPERATOR_EMAIL=[email protected]

If the variable is unset, the product falls back directly to the manual flow (no auto-activation attempt).

Idempotency in detail

The call is idempotent on (email, instance_id):

Scenario	Behavior
First call	Creates new APIKey + Instance, returns `api_key`
Same `(email, instance_id)` again	Returns the same `api_key`, `"reused": true`
Same `instance_id`, different email	`409 INSTANCE_EXISTS`
Same `email`, different `instance_id`	Creates new APIKey + Instance (new instance deploy)

This is what makes the route safe to call on container startup — if the container has registered before, it gets the same key; if it’s new, it gets a fresh key.

Containers that always generate a new UUID on every boot accumulate APIKeys (one per boot) under the same customer. For true idempotent behavior, persist the instance_id to a mounted volume (/data/instance-id) across restarts.

How to disable for my customer

In the customer portal (https://license.evolutionfoundation.com.br/portal) there is an “Auto-Activation by Email” toggle. When disabled:

All /v1/register/auto calls with your email return 403 AUTO_ACTIVATION_DISABLED
New deploys mandatorily go through the manual flow (browser + Magic Link/OAuth)
Your existing api_keys keep working normally

Recommended for customers who:

Operate in regulated environments and want an audit trail on every activation
Have a publicly-known email and want to reduce attack surface
Suspect misuse of the email

Auditing

Every call to /v1/register/auto produces an activation_logs row with alert_type = 'auto_activation'. The customer portal shows:

Date/time of each auto-activation
IP of the requesting server
Approximate location (country/city via GeoIP)
Result (created or reused)

If you see auto-activations you don’t recognize, suspend the corresponding key in the portal immediately — that revokes that instance’s access without affecting the others.

Next steps

Manual flow

Full /v1/register/init flow — required for first registration

Telemetry

What is sent on each licensing call

FAQ

Frequently asked questions

Overview

Licensing system summary

​When to use

​Endpoint

​Trust model

​Error codes

​Recommended client flow

​Standard env var

​Idempotency in detail

​How to disable for my customer

​Auditing

​Next steps

Manual flow

Telemetry

FAQ

Overview

When to use

Endpoint

Trust model

Error codes

Recommended client flow

Standard env var

Idempotency in detail

How to disable for my customer

Auditing

Next steps