Sign inSign up
Sign in

Token Rotation

Rotate account tokens, per-agent relay tokens, and device-side EWSP secrets without confusing the distinct trust boundaries in WakeLink.

The 3-Token Model

WakeLink authenticates three distinct actor types with three distinct token types. Each token carries the minimum privilege required for its role.

Token typePrefixScopeStorageRotation
Master API token
wl_
Full account access — Android app account auth, CLI, dashboard
Android Keystore / CLI config file
POST /api/v1/auth/token/rotate
Device relay token
wld_
Single-device WebSocket relay auth only
ESP32 NVS (on-chip flash)
POST /api/v1/agents/{agent_id}/rotate-token
Agent token
(chip-bound secret)
EWSP end-to-end crypto handshake only — never used for relay auth
ESP32 NVS
Re-provision the device
💡Tip

Key security property: Your master wl_ API token is never sent to ESP32 hardware. Only the per-agent wld_ relay token lives on the chip — so a stolen or compromised device cannot be used to access your account.

WebSocket Auth Logic

When an ESP32 connects to the relay, the server inspects the token prefix to determine how to authenticate it:

Token prefixLookup pathNotes
wld_
SHA-256 hash → nodes.agent_token_hash → owner user_id
Recommended path for all new firmware
wl_
SHA-256 hash → users.api_token_hash
Backward-compatible path for older firmware

Tokens are never stored in plaintext server-side — only their SHA-256 hashes are persisted.

Android Provisioning Flow

The Android app's "Add to Cloud" handshake ensures the master token stays on your phone:

1User taps "Add to Cloud"

The app calls POST /api/v1/agents/ authenticated with the master wl_ token. The server creates the device record and returns a fresh agent_token (wld_…) in AgentCreateResponse.agent_token. This is the only time the agent token is returned in plaintext.

2Token delivered to ESP over local TCP

The app calls setCloudConfig(cloudUrl, agent_token) over the local TCP provisioning channel. The master wl_ token never leaves the Android device.

3ESP stores token in NVS

The ESP32 saves the wld_ token to Non-Volatile Storage and uses it for all subsequent relay WebSocket connections.

⚠️Warning

The agent_token is returned once at device creation. If you lose it before provisioning the ESP, rotate the token to issue a new one — the old one is discarded.

Rotating an Agent Token

Rotate a per-agent relay token at any time without affecting your master credentials or other devices:

http
POST /api/v1/agents/{agent_id}/rotate-token
Authorization: Bearer wl_your_master_api_token
json
// Response
{
"agent_id": "esp32-living-room",
"agent_token": "wld_new_..."
}

Requirements:

  • The Authorization header must carry your master wl_ token — not the agent token being rotated
  • The agent_id must belong to your account

After Rotation

🚨Danger

The old agent token is immediately invalidated. The ESP32 will be disconnected from the relay as soon as rotation completes. All other devices and your master token are unaffected.

After rotating, re-provision the new wld_ token to the ESP32 using one of these methods:

  1. Android app — use the local provisioning flow on the same network
  2. ESP32 AP portal / JSON API — reset the device back to provisioning mode, reconnect to WakeLink-Setup, and save the new token alongside the rest of the relay settings

The ESP32 reconnects to the relay automatically once the new token is saved.

Rotating Your Master API Token

To rotate the account-level wl_ token:

http
POST /api/v1/auth/token/rotate
Authorization: Bearer wl_your_current_api_token

After rotation:

  • The old wl_ token is immediately invalid
  • Active login and WebSocket sessions are invalidated — the relay clears all sessions for the user after rotation
  • Update the token in your CLI config (~/.wakelink/env) and any automation scripts
  • The Android app will prompt you to re-authenticate once it detects the token has changed
  • Per-agent wld_ tokens are not affected — devices stay online

Password Change & Revocation

Changing your password triggers a full account credential rotation:

⚠️Warning

All active sessions and the current wl_ master API token are immediately invalidated on password change.

Per-device wld_ tokens are not invalidated — they are not derived from your password and remain valid until explicitly rotated.

If you suspect your account is compromised, rotate all agent tokens individually after changing your password to achieve full revocation across all hardware.

Curl Example: Rotating an Agent Token

bash
# Rotate the relay token for agent "esp32-living-room"
curl -X POST https://wakelink-project.org/api/v1/agents/esp32-living-room/rotate-token \
-H "Authorization: Bearer wl_your_master_api_token" \
-H "Content-Type: application/json"

# Response:
# {
# "agent_id": "esp32-living-room",
# "agent_token": "wld_new_..."
# }

# The new token is shown once — store it before re-provisioning the ESP32
NEW_AGENT_TOKEN="wld_new_..."

# Re-provision the ESP32 with the new token through the Android setup flow
# or by resetting the board to AP mode and re-entering the provisioning fields

Continue reading

Security & EncryptionTroubleshooting