The reCAPTCHA external step has domain validation issues (HA's
hostname isn't in the allowed list for any reCAPTCHA key). Instead,
the config flow now asks the user to:
1. Open perfectdraft.com/en-gb/customer/account/login
2. Run one console command to generate a token
3. Paste the token into the HA config flow
Clear instructions are shown in the flow description. The token
expires in 2 minutes, and the error message tells the user to
try again with a fresh token if it fails.
Removed the external step, HTML page, and HTTP views entirely.
Much simpler code, no moving parts.
Made-with: Cursor
Chronological account of every approach tried, what failed, why,
and how the working solution was eventually found. Includes the
exec summary of what actually works at the top.
Made-with: Cursor
Breakthrough: discovered the web reCAPTCHA Enterprise key
(6LcZQiUo...) from perfectdraft.com with action "Magento/login"
is accepted by the /authentication/sign-in API endpoint when
generated from a real browser. Token refresh works via direct
AWS Cognito InitiateAuth (bypasses API gateway, no reCAPTCHA).
Cognito details extracted from JWT:
Pool: eu-west-1_UXWVyvlHR
Client: 57ddq2ppqg2jcpup06r2g1deur
Real API response fields mapped:
/api/me → perfectdraftMachines[].id
/api/perfectdraft_machines/{id} → details.temperature,
details.kegVolume, details.connectedState, details.doorClosed,
details.numberOfPoursSinceStartup, details.volumeOfLastPour,
details.firmwareVersion, details.serialNumber, setting.mode
Changes:
- api.py: Cognito direct refresh, correct sign-in endpoint
- config_flow.py: external step with web reCAPTCHA on HA page
- const.py: Cognito config, web reCAPTCHA key
- coordinator.py: real field name extraction
- sensor.py: 8 sensors with real field mappings (temperature,
keg remaining %, connection, door, pours, last pour, firmware, mode)
- Removed image.py (API doesn't expose keg images)
- Restored static/recaptcha.html with Enterprise JS
Made-with: Cursor
Decompiled PerfectDraft APK kept locally for reference.
Emulator approach failed: ARM64 native libs can't run on x86_64
emulator, and ARM64 emulation isn't supported by Android emulator
on x86_64 hosts.
Made-with: Cursor
The Android reCAPTCHA Enterprise key cannot be used from any
non-Android context (browser, server, headless). Certificate
pinning prevents MITM token capture. Every approach to bypass
reCAPTCHA has been exhausted.
New approach: user provides UserId + RefreshToken (one-time
extraction from the PerfectDraft app via HTTP Toolkit or similar).
The integration validates by calling /auth/renewaccesstokens,
which does NOT require reCAPTCHA, then refreshes forever.
Changes:
- config_flow.py: two-step flow (email, then tokens), validates
via refresh endpoint, reauth asks for fresh tokens
- api.py: refresh_access_token() calls /auth/renewaccesstokens
with {UserId, RefreshToken}, removed authenticate() method,
added x-api-key header to all authenticated requests
- const.py: added CONF_USER_ID, removed reCAPTCHA constants
- __init__.py: passes user_id to client.set_tokens()
- strings.json + translations: updated for new flow steps
- Deleted recaptcha.py and static/recaptcha.html
- test_harness.py: updated for refresh-based flow
Made-with: Cursor
Decompiled PerfectDraft APK (Expo/React Native + Hermes bytecode).
Key discoveries:
API has TWO auth systems:
- /authentication/sign-in (Cognito + Lambda trigger) — old
- /auth/signin (.NET backend) — new, same reCAPTCHA gate
Critical find: /auth/renewaccesstokens accepts POST with
{UserId, RefreshToken} and does NOT require reCAPTCHA.
Full API surface discovered:
- /auth/signin, /auth/renewaccesstokens, /auth/signout
- /auth/changepassword, /auth/confirmsignup
- /api/perfectdraft_machines/, /api/perfectdraft_machines/{id}
- /api/perfectdraft_machine_kegs
- /api/pda_machines/add
- /api/countries, /api/customer_product_ratings
reCAPTCHA is Android Enterprise key — cannot generate valid
high-score tokens from any non-Android context. Both /auth/signin
and /authentication/sign-in require it. But refresh does not.
Strategy: one-time token capture, then refresh forever.
Made-with: Cursor
The Android key (6LdrqmAp...) only works with the Android SDK —
it rejects all web-based token generation with "Invalid domain."
Discovered that perfectdraft.com's web login uses a separate
Enterprise web key (6LcZQiUo...) with action "Magento/login".
Testing confirmed the API at api.perfectdraft.com accepts tokens
from this web key. The only remaining requirement is a high
reCAPTCHA score, which a real user's browser will provide.
The external step flow now uses:
- Enterprise JS (recaptcha/enterprise.js)
- Web site key: 6LcZQiUoAAAAAAO3JUjLiT470c-pNXbWyepuvMtV
- Action: Magento/login
Removed server-side token generation attempt from config flow
since it cannot produce high-score tokens.
Made-with: Cursor
test_harness.py exercises the full API flow without HA.
Credentials go in .credentials.json (gitignored).
Key findings from testing:
- reCAPTCHA is Enterprise, not standard v3
- Server-side anchor/reload tokens work but carry wrong action
- Playwright tokens carry correct action but get low trust score
- API validates both action string AND score threshold
- The exact action string is "Android_recaptchaThatWorks/login"
- Auth endpoint: POST /authentication/sign-in returns
AccessToken, IdToken, RefreshToken on success
Made-with: Cursor
The browser-based reCAPTCHA approach fails with "Invalid domain"
because PerfectDraft's site key is registered for their domains,
not for the HA instance hostname.
New approach: generate the token server-side via the reCAPTCHA
anchor/reload HTTP endpoints, bypassing domain validation entirely.
Falls back to browser-based external step if server-side fails.
Also adds better error logging in the auth step.
Made-with: Cursor
The external step mechanism requires a specific flow:
1. async_external_step() pauses the flow
2. Callback stashes token in hass.data and calls async_configure()
with no user_input to signal completion
3. HA calls async_step_recaptcha_done() which picks up the token
4. async_external_step_done() transitions to async_step_finish()
5. async_step_finish() does the actual API authentication
Previously tried to resume the flow by passing user_input directly
to async_configure(), which doesn't work with external steps.
Made-with: Cursor
Scaffolds the repo with agent workflow config (AGENTS.md, .gitignore),
openspec tooling, and the perfectdraft-integration change proposal
with design, specs (api-client, config-flow, entities, hacs-packaging),
and implementation tasks — ready for apply phase.
Made-with: Cursor