SDK Token Configuration
Relevant source files
The following files were used as context for generating this wiki page:
SDK Token Configuration defines how an ESP32 device identifies itself and authenticates with the Muse AI infrastructure. Every gadget built using the Muse Gadget SDK requires a unique SDK token (mgst_...) to pair with the Muse mobile application and establish a secure connection to a Virtual Machine (VM).
The firmware incorporates the token during the build process or manual configuration. It uses the token as a primary identifier to mint short-lived device access and refresh tokens. While the SDK token resides within the firmware, the system treats it as an identifier rather than a secret password, though users must revoke and regenerate leaked tokens via the Muse developer portal.
Sources: board-port/esp32/README.md:23-26, board-port/esp32/README.md:144-147, board-port/esp32/AGENTS.md:65-69
Configuration Methods
You can configure the SDK token using environmental variables, build-time definitions, or interactive configuration menus.
Build-Time Injection
The most common method involves setting the CONFIG_GADGET_SDK_TOKEN parameter. In automated environments like GitHub Actions, the workflow injects this from a repository secret.
- name: Build firmware
env:
GADGET_SDK_TOKEN: ${{ secrets.GADGET_SDK_TOKEN }}
run: |
printf 'CONFIG_GADGET_SDK_TOKEN="%s"\n' "$GADGET_SDK_TOKEN" > /tmp/sdkconfig.token
idf.py ... -DSDKCONFIG_DEFAULTS="...;/tmp/sdkconfig.token" build
Sources: workflows/build-release.yml:45-54, README.md:43-46
Interactive Configuration
For local development, use the ESP-IDF menuconfig tool to set the token manually. Navigate to ESP32 Device SDK > Muse Gadgets SDK token to enter the string.
Sources: board-port/esp32/README.md:83-85, board-port/esp32/AGENTS.md:65-68
Token Data Flow and Authentication
The firmware manages three distinct types of tokens to maintain a secure session with the Muse VM.
| Token Type | Purpose | Persistence |
|---|---|---|
| SDK Token | Original identifier (mgst_...) used to authorize pairing and initial token minting. | Hardcoded in firmware config. |
| Access Token | Short-lived credential used for direct API calls and Noise session authentication. | Stored in NVS (Flash). |
| Refresh Token | Longer-lived credential used to obtain a new Access Token without re-pairing. | Stored in NVS (Flash). |
Sources: board-port/esp32/main/app.c:380-394, board-port/esp32/AGENTS.md:65-69, board-port/esp32/README.md:144-147
Token Minting and Refresh Logic
Upon successful Wi-Fi connection and pairing, the device calls the vm_api_mint_device_token endpoint. It provides the SDK token and the device's unique Node ID to receive an Access/Refresh token pair. The system proactively refreshes the Access Token based on uptime to prevent session expiration.
This diagram illustrates the lifecycle of authentication tokens from boot to session establishment.
Sources: board-port/esp32/main/app.c:429-450, board-port/esp32/main/app.c:1300-1310
Security and Encryption
The SDK recommends protecting stored tokens using Non-Volatile Storage (NVS) encryption.
- NVS Encryption: Enabling
CONFIG_HOMEHUB_NVS_ENCRYPTIONprevents attackers with physical access from reading Wi-Fi credentials and device tokens. The encryption key derives from an HMAC key in the eFuse block, generated on the first boot. - Token Revocation: If an SDK token is leaked, you must revoke it at
gadgets.muse.ai, generate a new one, and rebuild the firmware. - Authentication Failures: If a Noise session returns
ws_auth_failed, the device triggers an immediate refresh attempt. If the refresh token is also rejected, the device may unpair to prevent unauthorized access.
Sources: board-port/esp32/README.md:149-155, board-port/esp32/main/app.c:475-490, board-port/esp32/main/noise_control.cpp:1115-1125
Implementation Details
The identity module handles the SDK token during runtime. The vm_api module uses it for server communication.
Key Functions
identity_sdk_token(): Returns the SDK token string configured at build time.vm_api_set_sdk_token(token): Configures the API client to use the specific SDK token for subsequent requests.ensure_access_token_ready_with_gate_held(): Coordinates the logic to migrate legacy tokens, mint new ones, or refresh existing ones.mint_and_store_device_tokens_unlocked(): Performs the actual network call to exchange the SDK token for device credentials.
Sources: board-port/esp32/main/app.c:429-435, board-port/esp32/main/app.c:468-472, board-port/esp32/main/app.c:1102-1105
Heartbeat Reporting
The device includes the first 12 characters of the SDK token in the serial boot log for identification purposes. During the Noise session, the device attempts a proactive refresh at least once per boot to report the current SDK token version to the Muse backend.
Sources: board-port/esp32/main/app.c:459-462, board-port/esp32/main/app.c:1111-1113
Summary
SDK Token Configuration is the foundational security mechanism for Muse gadgets. It transitions the device from a generic hardware build to a specific, authenticated agent. By injecting the token at build time and managing a secondary token pair in encrypted NVS, the system balances ease of setup with secure, long-term operation.