Authentication

Aelio uses three separate authentication mechanisms. Do not conflate them.

1. SDK authentication

The SDK connects to the server over WebSocket at /sdk with a Bearer token:

Authorization: Bearer <AELIO_SDK_SECRET>

• Constant-time comparison (timingSafeEqual)
• Max 32 concurrent SDK connections
• Must send register frame within 15s or connection is closed
• Auto-reconnect with exponential backoff

await aelio.listen({
  secret: process.env.AELIO_SDK_SECRET,
  url: 'ws://127.0.0.1:3010',
});

2. Widget authentication (magic link)

For production, the widget uses short-lived session tokens:

Your backend → POST /auth/magic-link (Bearer secret)
  → magic link URL
  → user clicks → GET /auth/verify?token=...
  → sessionToken
  → widget init with authToken

Session tokens are HMAC-SHA256 signed, TTL default 60 minutes. The server verifies the token matches customerId.

See Widget Authentication for the full flow.

3. Protected HTTP routes

These routes require Authorization: Bearer <AELIO_SDK_SECRET>:

Also accepts x-aelio-secret header as an alternative.

4. WhatsApp webhook auth

• GET verification: hub.verify_token must match config
• POST messages: HMAC x-hub-signature-256 verified against raw body + app_secret

Security rules

Anonymous mode (dev only)

identity:
  allow_anonymous: true

Allows widget init with just customerId and email, no token required.