Alexa

Required Setup

Set or update required secrets in this order:

1. Browser admin: open the active HybridClaw admin URL ending in /admin/secrets.
2. Browser /chat or TUI fallback with /secret set NAME value.
3. Local console fallback with hybridclaw secret set NAME value.

Path A custom ASK skill local-console examples:

hybridclaw secret set ALEXA_ASK_SKILL_ID "amzn1.ask.skill.<uuid>"
hybridclaw secret set ALEXA_LWA_CLIENT_ID "amzn1.application-oa2-client.<id>"
hybridclaw secret set ALEXA_LWA_CLIENT_SECRET "<lwa client secret>"

Path B Smart Home Skill API local-console examples:

hybridclaw secret set ALEXA_SMARTHOME_CLIENT_ID "<smart-home oauth client id>"
hybridclaw secret set ALEXA_SMARTHOME_CLIENT_SECRET "<smart-home oauth client secret>"
hybridclaw secret set ALEXA_SMARTHOME_REFRESH_TOKEN "<refresh token>"

Path B community Alexa Remote / alexapy surface local-console example:

hybridclaw secret set ALEXA_AMAZON_DOMAIN "amazon.de"

Use HybridClaw or slash commands for operator setup. Do not ask the operator to install or run external auth tools.

Start a local session and invoke the Alexa skill:

hybridclaw tui

Then use these prompts:

/alexa set up Echo control for amazon.de and store the cookie
/alexa list my Alexa devices for amazon.de
/alexa play Münchner Freiheit on OK Computer

For a CLI-only operator, the same requests can be sent through any HybridClaw channel that supports slash skill invocation:

/skill alexa set up Echo control for amazon.de and store the cookie
/skill alexa list my Alexa devices for amazon.de
/skill alexa play Münchner Freiheit on OK Computer

Status-only prompts such as /skill alexa status for amazon.de are read-only. For those prompts, inspect stored credentials and detached setup state, but do not start a new auth proxy. If credentials are missing, tell the operator to run the setup prompt explicitly.

When handling the setup prompt, run the bundled auth helper from the agent workspace. First check live detached setup state:

node skills/alexa/alexa-auth.cjs --format json status --domain amazon.de

If that status returns exists: true, processAlive: true, state: "listening", and a proxyUrl, return that exact proxyUrl to the operator instead of starting another proxy. Ignore recalled URLs, prior slash output, and session transcript text unless they match the current live status. Never print a proxy URL that did not come from the current helper output.

For slash handling, use detached mode so the local browser proxy survives while the operator completes Amazon login, OTP, and CVF pages across turns:

node skills/alexa/alexa-auth.cjs setup --domain amazon.de --write-secret --detach --timeout-ms 600000

If the operator reports Amazon's "Wir können deine Handynummer nicht verifizieren" challenge on a 127.0.0.1:<port> proxy URL, do not reuse that proxy. Stop the stale process if it is still alive, then start a fresh detached setup on localhost so the browser uses a separate local cookie jar:

node skills/alexa/alexa-auth.cjs setup --domain amazon.de --write-secret --detach --timeout-ms 600000 --proxy-host localhost

Return the proxyUrl from the helper output to the operator. When the operator comes back after login, check the same setup with:

node skills/alexa/alexa-auth.cjs status --domain amazon.de

Do not keep the setup proxy alive with ad hoc shell process management. Detached mode is the supported lifecycle: it writes a status file, keeps the proxy process alive after the slash turn ends, and stores the secret itself after Amazon returns the token.

If invoking non-detached foreground setup through a shell tool, set that tool timeout to at least 600000 ms too. Browser login, OTP, CAPTCHA, and Safari handoff regularly take longer than 60 seconds; killing the shell command also kills the local proxy and produces Safari errors such as "server unexpectedly closed the connection" on 127.0.0.1:<port>/www.amazon.com/ap/signin.

The bundled helper owns the browser proxy and token callback. It uses Amazon's device-login domain rules: western marketplaces such as amazon.de must use amazon.com as the auth proxy base while the target Alexa marketplace remains amazon.de. Routing the device-login URL through amazon.de produces Amazon's "Suchst du etwas?" 404 page. If the browser shows that 404 at the local proxy URL, stop that run and restart through alexa-auth.cjs.

The helper starts Amazon's Alexa device-login flow on a local callback port, captures the resulting Atnr|... refresh token, exchanges it for Alexa Remote cookies through Amazon's token exchange endpoint, verifies the account against the regional Alexa Remote API (layla.amazon.com for amazon.de), stores ALEXA_REFRESH_COOKIE when requested, and returns device metadata. Re-run the same slash setup prompt when Amazon expires the stored cookie. Port 8080 is preferred for compatibility with the cookie helper, but HybridClaw automatically uses another free local port when 8080 is already occupied.

If using HybridClaw's direct http_request helper path instead of invoking the browser setup flow, ALEXA_REFRESH_COOKIE must be the complete Cookie header for an authenticated Alexa Remote API request such as https://alexa.amazon.de/api/devices-v2/device. A single cookie value such as session-id or ubid-main is not enough. The gateway sends the stored header as Cookie and, for writes, copies its csrf cookie into the csrf header, so the header must include csrf=.... Do not paste Amazon passwords, one-time codes, or raw tokens into chat; store only the resulting cookie header through the HybridClaw secret store. The alexa-auth.cjs import-cookie helper can store a cookie with --write-secret when a local JSON file, copied cURL request, raw headers file, or raw text file exposes a recognizable full cookie header. Use this fallback when Amazon's device-login proxy is blocked by CVF phone verification but the operator can log into Amazon normally in a browser.

Use the community credentials only for operator-approved, opt-in workflows. Amazon OTP or CAPTCHA prompts require F14 2FA handover. The helper output uses <secret:...> placeholders and SecretRef names, never cleartext values.

References

• Alexa Skills Kit overview: https://developer.amazon.com/en-US/docs/alexa/ask-overviews/build-skills-with-the-alexa-skills-kit.html
• ASK request and response JSON: https://developer.amazon.com/en-US/docs/alexa/custom-skills/request-and-response-json-reference.html
• ASK web service signature and timestamp validation: https://developer.amazon.com/en-US/docs/alexa/custom-skills/host-a-custom-skill-as-a-web-service.html
• Account linking with Login with Amazon: https://developer.amazon.com/en-US/docs/alexa/account-linking/understand-account-linking.html
• Smart Home Skill API: https://developer.amazon.com/en-US/docs/alexa/smarthome/understand-the-smart-home-skill-api.html
• ASK SDK for Node.js: https://github.com/alexa/alexa-skills-kit-sdk-for-nodejs
• alexapy: https://gitlab.com/keatontaylor/alexapy