20 KiB
PerfectDraft Pro API Discovery
TL;DR — What Actually Works
Authentication:
- Load
https://www.perfectdraft.com/en-gb/customer/account/loginin a real browser - Execute
grecaptcha.enterprise.execute('6LcZQiUoAAAAAAO3JUjLiT470c-pNXbWyepuvMtV', {action: 'Magento/login'})to get a reCAPTCHA token - POST to
https://api.perfectdraft.com/authentication/sign-inwith{email, password, recaptchaToken, recaptchaAction: "Magento/login"}and headerx-api-key: cAyzERqthCJXYVExjNAhr9CzE8ncLN2cQK3WGK10 - Returns
{AccessToken, IdToken, RefreshToken}
Token refresh (no reCAPTCHA needed, ever again):
- POST directly to AWS Cognito:
https://cognito-idp.eu-west-1.amazonaws.com/ - Header:
X-Amz-Target: AWSCognitoIdentityProviderService.InitiateAuth - Body:
{AuthFlow: "REFRESH_TOKEN_AUTH", ClientId: "57ddq2ppqg2jcpup06r2g1deur", AuthParameters: {REFRESH_TOKEN: "..."}} - Returns fresh
AccessTokenandIdToken(1 hour TTL). The originalRefreshTokenstays valid.
Data endpoints:
GET /api/me→ user profile withperfectdraftMachines[].idGET /api/perfectdraft_machines/{id}→ full machine telemetry indetailsobject
Key constants:
- API base:
https://api.perfectdraft.com - x-api-key:
cAyzERqthCJXYVExjNAhr9CzE8ncLN2cQK3WGK10 - reCAPTCHA web key:
6LcZQiUoAAAAAAO3JUjLiT470c-pNXbWyepuvMtV(from perfectdraft.com login page) - reCAPTCHA action:
Magento/login - Cognito region:
eu-west-1 - Cognito User Pool:
eu-west-1_UXWVyvlHR - Cognito Client ID:
57ddq2ppqg2jcpup06r2g1deur
The Journey
1. Starting from community attempts
The only existing integration attempt was matthewcky2k/homeassistant-perfectdraft, discussed in a Home Assistant forum thread. It provided the initial clues:
- API base URL:
https://api.perfectdraft.com - Sign-in endpoint:
POST /authentication/sign-in - x-api-key:
cAyzERqthCJXYVExjNAhr9CzE8ncLN2cQK3WGK10 - reCAPTCHA site key:
6LdrqmApAAAAAB_kTEHVnx9pua3TMurf4i75a-aQ - Request body:
{email, password, recaptchaToken, recaptchaAction: "Android_recaptchaThatWorks/login"} - Response:
{AccessToken, IdToken, RefreshToken} - Data endpoints:
GET /api/me,GET /api/perfectdraft_machines/{id}
The existing integration didn't work because:
- It asked users to manually paste a reCAPTCHA token (tokens expire in ~2 minutes)
- It used synchronous
requestsinstead of asyncaiohttp - No
DataUpdateCoordinator(each sensor polled independently → IP bans) - Broken HACS packaging (files didn't download properly)
- No token refresh logic
A forum user had sniffed the app traffic and confirmed: "It's only used at the point of initial sign-in to the API, once you are authenticated you have a token to use." This was the key insight that refresh tokens existed.
2. Server-side reCAPTCHA token generation (FAILED)
Approach: Use the reCAPTCHA anchor/reload HTTP endpoints to generate tokens without a browser.
What happened: The anchor endpoint (/recaptcha/api2/anchor and /recaptcha/enterprise/anchor) returned tokens, but the reload endpoint generated tokens without the correct action binding. The API validated that the action embedded in the token matched "Android_recaptchaThatWorks/login".
Error: "The reCAPTCHA action does not match the expected action."
Why it failed: reCAPTCHA v3/Enterprise embeds the action string cryptographically in the token during grecaptcha.execute(). The anchor/reload HTTP flow doesn't support specifying a custom action — that's a client-side-only feature.
3. Browser-based reCAPTCHA on HA external step (FAILED)
Approach: Serve a small HTML page from Home Assistant during the config flow that loads the reCAPTCHA JS and generates a token invisibly.
What happened: The reCAPTCHA widget displayed "ERROR for site owner: Invalid domain" in the corner. The execute() call either failed silently or returned a garbage token.
Why it failed: The reCAPTCHA site key 6LdrqmAp... was registered as an Android-only key in Google's reCAPTCHA Enterprise console. It was never meant to work in a web browser. The web api.js rejected it because the domain (yellow:8123) wasn't in the allowed list — and no web domain would be, because it's not a web key.
4. Playwright headless browser with correct action (FAILED)
Approach: Use Playwright to load a page on perfectdraft.com (via route interception), execute reCAPTCHA with the correct action string, and use the resulting token.
What happened: Tokens were generated with the correct action. The API accepted the action but rejected the score.
Error: "The reCAPTCHA score is below the set threshold."
Why it failed: reCAPTCHA Enterprise assigns a trust score based on browser behavior, device fingerprinting, and interaction patterns. Headless browsers (even with stealth patches, mobile user agents, and anti-detection measures) consistently received low scores. Tried:
- Headless Chromium
- Headed Chromium
- Mobile user agent (Pixel 8)
playwright-stealthlibrary--disable-blink-features=AutomationControlled- Removing
navigator.webdriver
All received scores below PerfectDraft's threshold. reCAPTCHA Enterprise is specifically designed to detect automated browsers.
5. Discovering the web reCAPTCHA key (FAILED initially, SUCCEEDED later)
Approach: Check if perfectdraft.com uses a different reCAPTCHA key for their web login.
Discovery: The web login page at perfectdraft.com/en-gb/customer/account/login loads reCAPTCHA Enterprise with a different key: 6LcZQiUoAAAAAAO3JUjLiT470c-pNXbWyepuvMtV, using action Magento/login.
First test: Generated a token with Playwright using this web key and Magento/login action, sent it to /authentication/sign-in.
Result: "The reCAPTCHA score is below the set threshold." — same score problem from headless browser.
Key insight: The API did accept the web key with Magento/login action. The only issue was the automated browser's low score. A real human browser would get a high enough score. This insight was filed away and became the breakthrough later.
6. PCAPdroid network capture (FAILED)
Approach: Capture the PerfectDraft app's network traffic on a real phone using PCAPdroid with TLS decryption.
What happened: First capture (without TLS decryption) showed only encrypted traffic. Second capture (with TLS decryption enabled) also showed only encrypted traffic.
Why it failed: The PerfectDraft app uses certificate pinning. When PCAPdroid's MITM CA certificate was active, the app's OkHttp client rejected the connection. The app refused to log in entirely when MITM was detected.
7. ADB token extraction (NOT ATTEMPTED)
Approach: Connect the phone via USB debugging and extract tokens from the app's storage.
Why not attempted: The user (rightfully) refused to enable USB debugging on a phone with banking certificates, citing the risk of WiFi debugging being enabled by default on some Android devices.
8. APK decompilation and analysis
Approach: Download and decompile the PerfectDraft APK to understand the auth flow.
Source: Downloaded PerfectDraft v3.5.5 from apk.cafe (split APK bundle: base + arm64 + en + xxhdpi).
Tools: apktool for smali decompilation, strings for Hermes bytecode analysis.
Key discoveries from the APK:
The app is built with Expo/React Native with Hermes bytecode. The JS bundle is compiled to Hermes binary format, making it harder to read than plain JS.
BuildConfig.smali revealed all configuration constants:
API_KEY = cAyzERqthCJXYVExjNAhr9CzE8ncLN2cQK3WGK10
BASE_URL = https://api.perfectdraft.com
CAPTCHA_KEY = 6LdXriEoAAAAAJbpl0ApCsOpaRjLfKfKpxn07Hv4 (third key!)
CAPTCHA_SITE_KEY = https://www.perfectdraft.com
PERFECTSERVE_API_KEY = 540297f2-b287-4adb-afc1-cb2166cfcb14
NUCLEUS_URL = https://api.perfectdraft.com
ONBASS_URL = https://eur-04530-pdiot-onbass-uks-prod-fnapp.azurewebsites.net/api
KEG_RETURN_API = https://keg-return-service.api.perfectdraft.tech
Hermes bundle string extraction revealed a second auth system:
/auth/signin— a .NET backend (separate from the Cognito/authentication/sign-in)/auth/renewaccesstokens— token refresh without reCAPTCHA!/auth/signout,/auth/changepassword,/auth/confirmsignup/api/perfectdraft_machines/,/api/perfectdraft_machine_kegs@google-cloud/recaptcha-enterprise-react-native— confirms Enterprise reCAPTCHA via native Android SDK
The refresh endpoint discovery: Probing /auth/renewaccesstokens with an empty body returned {"UserId":["The UserId field is required."],"RefreshToken":["The RefreshToken field is required."]} — confirming it exists and telling us the exact field names. This endpoint does NOT require reCAPTCHA.
9. The third reCAPTCHA key (FAILED)
Approach: The APK's CAPTCHA_KEY (6LdXriEoAAAAAJbpl0ApCsOpaRjLfKfKpxn07Hv4) was different from both the Android key and the web key. Tested it via anchor/reload and Playwright.
What happened: Google's reCAPTCHA JS returned 400 Bad Request when loaded with this key. The anchor endpoint returned pages without tokens.
Why it failed: This is also an Android-only key. The CAPTCHA_SITE_KEY = https://www.perfectdraft.com in the config is misleading — it's used as a parameter in the Android reCAPTCHA Enterprise SDK call, not as a web origin. All three keys are Android-only:
6LdrqmAp...— from community research6LdXriEo...— from APK BuildConfig6LcZQiUo...— from perfectdraft.com web page (this one IS a web key)
10. Android emulator approach (FAILED)
Approach: Run the PerfectDraft app in an Android emulator on the battlestation, with mitmproxy intercepting traffic.
What happened: Installed Android SDK, created an x86_64 AVD with Google APIs image, installed the APK.
Failure 1: The APK required split APKs (INSTALL_FAILED_MISSING_SPLIT). Installed with all splits.
Failure 2: The app crashed with SoLoaderDSONotFoundError: couldn't find DSO to load: libreactnative.so. The arm64 native libraries couldn't run on the x86_64 emulator despite ARM translation support — React Native's native bridge was too complex for the translation layer.
Failure 3: ARM64 system images exist but the Android emulator binary doesn't support ARM64 on x86_64 hosts (FATAL: Avd's CPU Architecture 'arm64' is not supported by the QEMU2 emulator on x86_64 host).
11. K8s ARM64 pod approach (FAILED)
Approach: Use a Raspberry Pi 4B node in the Kubernetes cluster to run an ARM64 Android emulator natively.
What happened: Created a pod on an ARM64 node, installed Java and Android SDK. The emulator package doesn't exist for ARM64 Linux — Google only distributes it for x86_64.
Why it failed: No ARM64 Android emulator binary exists. Would need QEMU to boot an Android image, which would be extremely slow on a Pi 4B inside a K8s pod without KVM.
12. APK patching — removing cert pinning (FAILED, multiple attempts)
Approach: Modify the PerfectDraft APK to disable certificate pinning, install on the user's real phone, capture traffic with PCAPdroid.
Discovery: Analysis of the smali code revealed that OkHttp's CertificatePinner.Builder.add() is never called — there are no hardcoded certificate pins. The app relies solely on Android's default trust store behavior (which doesn't trust user-installed CAs on Android 7+).
Attempt 1 — Full apktool decompile/rebuild: Decompiled with apktool d, added network_security_config.xml trusting user CAs, patched manifest, no-oped CertificatePinner.check() in smali, rebuilt with apktool b. App crashed immediately on launch. Apktool corrupted the Hermes bytecode or resource references during the decompile/recompile cycle.
Attempt 2 — apktool with -s (skip DEX): Decompiled resources only, kept DEX files intact, added network security config, rebuilt. App still crashed — the manifest and resources.arsc were subtly corrupted by apktool's resource recompilation.
Attempt 3 — Binary manifest patching: Extracted the apktool-rebuilt manifest and resources.arsc, injected them into the original APK via zip commands, keeping all DEX files original. App crashed — the resources.arsc from apktool didn't match the original resource IDs (app icon was missing, replaced with generic Android icon).
Attempt 4 — DEX-only patching: Created a TrustAllCerts class in smali, patched OkHttpClientProvider.createClientBuilder() to inject a trust-all SSLSocketFactory. Rebuilt only classes3.dex via apktool, injected it into the original APK keeping everything else byte-for-byte identical. Manifest and resources verified identical via md5sum. App reported "not compatible with your phone" — the original manifest's requiredSplitTypes attribute demanded the architecture split APK.
Attempt 5 — Binary manifest + DEX patch: Patched the requiredSplitTypes string in the binary manifest by finding the UTF-16LE encoded string and replacing it with spaces (same byte length). Combined with the DEX patch. This was never tested on the phone because the user was (understandably) fatigued by the cycle.
13. The breakthrough — real browser on perfectdraft.com
Approach: Revisiting discovery #5 — the web reCAPTCHA key works, it just needs a real browser with a high trust score.
The test: User opened https://www.perfectdraft.com/en-gb/customer/account/login in Chrome, opened the dev console, and ran:
grecaptcha.enterprise.execute('6LcZQiUoAAAAAAO3JUjLiT470c-pNXbWyepuvMtV', {action: 'Magento/login'}).then(t => console.log(t))
This generated a valid token from a real browser on the real domain — high reCAPTCHA score.
The auth call:
POST https://api.perfectdraft.com/authentication/sign-in
x-api-key: cAyzERqthCJXYVExjNAhr9CzE8ncLN2cQK3WGK10
{email, password, recaptchaToken: <token>, recaptchaAction: "Magento/login"}
Result: 200 OK with {AccessToken, IdToken, RefreshToken}.
Why it worked: The API's Cognito Lambda trigger validates the reCAPTCHA token against Google's assessment API. It checks:
- The action matches a configured action (both
Android_recaptchaThatWorks/loginandMagento/loginare configured) - The score is above a threshold
- The token is valid for one of the registered site keys
The web key (6LcZQiUo...) is registered for perfectdraft.com. A real browser on that domain gets a high score. The API accepts tokens from this key with the Magento/login action.
14. Cognito direct refresh
Discovery: Decoding the JWT AccessToken revealed:
iss:https://cognito-idp.eu-west-1.amazonaws.com/eu-west-1_UXWVyvlHRclient_id:57ddq2ppqg2jcpup06r2g1deursub: the user's UUID
The refresh call:
POST https://cognito-idp.eu-west-1.amazonaws.com/
Content-Type: application/x-amz-json-1.1
X-Amz-Target: AWSCognitoIdentityProviderService.InitiateAuth
{AuthFlow: "REFRESH_TOKEN_AUTH", ClientId: "57ddq2ppqg2jcpup06r2g1deur", AuthParameters: {REFRESH_TOKEN: "..."}}
Result: 200 OK with fresh AccessToken and IdToken (1 hour TTL).
This bypasses the API gateway entirely — no reCAPTCHA, no x-api-key, no rate limiting. The refresh token appears to be long-lived (standard Cognito default is 30 days).
15. Full API mapping
With valid tokens, the complete API surface was mapped:
GET /api/me — User profile:
{
"id": 2556952,
"cognitoId": "8a1289be-...",
"email": "...",
"perfectdraftMachines": [{"id": 401294, "deviceId": "...", "type": "pd_pro"}],
"country": {"countryCode": "DE"}
}
GET /api/perfectdraft_machines/{id} — Machine telemetry:
{
"id": 401294,
"type": "pd_pro",
"setting": {
"temperature": 3,
"temperatureMin": 3,
"temperatureMax": 7,
"temperatureUnit": "C",
"mode": "standard",
"boost": false
},
"details": {
"serialNumber": "111EU2516001686",
"firmwareVersion": "v3.16.0-5",
"temperature": 3,
"displayedBeerTemperatureInCelsius": 3,
"displayedBeerTemperatureInFahrenheit": 37,
"kegVolume": 5.13,
"kegPressure": 114.33,
"doorClosed": true,
"connectedState": true,
"numberOfPoursSinceStartup": 30,
"volumeOfLastPour": 0.289,
"durationOfLastPour": 3701,
"kegType": "PD",
"errorCodes": 0
}
}
GET /api/perfectdraft_machine_kegs — Keg history (global, not per-machine filterable without the machine's own keg endpoint).
GET /api/products/{id} — Minimal product data (just {id}), no keg name or image available from this API.
Summary of reCAPTCHA keys
| Key | Source | Type | Works from browser? |
|---|---|---|---|
6LdrqmAp... |
Community research / forum | Android Enterprise | No |
6LdXriEo... |
APK BuildConfig | Android Enterprise | No |
6LcZQiUo... |
perfectdraft.com login page | Web Enterprise | Yes |
Summary of auth endpoints
| Endpoint | reCAPTCHA required? | Notes |
|---|---|---|
POST /authentication/sign-in |
Yes (Cognito + Lambda trigger) | Accepts web key with Magento/login |
POST /auth/signin |
Yes (.NET backend) | Always returns "Captcha Failure" without valid token |
POST /auth/renewaccesstokens |
No | Needs {UserId, RefreshToken}, returned 409 Conflict in testing |
Cognito InitiateAuth |
No | Direct Cognito call, works perfectly for refresh |
Why This Succeeded Where Others Failed
Every previous attempt to build a PerfectDraft Home Assistant integration hit the reCAPTCHA wall and stopped. The forum thread has been open since December 2022. People got IP-banned, gave up on token generation, built broken integrations that asked users to paste ephemeral hex codes. The integration was widely considered impossible without PerfectDraft's cooperation.
The breakthrough came from connecting three observations that nobody had put together before:
-
PerfectDraft's web store uses a different reCAPTCHA key than the mobile app — and the API accepts tokens from both. Everyone focused on the Android key from the app traffic (
6LdrqmAp...), which is an Android-only Enterprise key that cannot generate valid tokens from any browser. But the Magento web store atperfectdraft.comloads a web Enterprise key (6LcZQiUo...) that works from any browser on that domain. The API's Cognito Lambda trigger is configured to accept tokens from either key. -
The Cognito User Pool can be called directly for token refresh, bypassing the API gateway entirely. The reCAPTCHA check lives in a Lambda trigger on the API gateway's
/authentication/sign-inendpoint. But the underlying Cognito User Pool (eu-west-1_UXWVyvlHR) accepts standardREFRESH_TOKEN_AUTHcalls with no reCAPTCHA, no API key, no rate limiting. The pool ID and client ID were extracted from the JWT claims in the access token. This means reCAPTCHA is only needed once — at initial sign-in — and never again. -
A real human browser on
perfectdraft.comgets a high enough reCAPTCHA score. Automated browsers (Playwright, headless Chrome, even headed Chrome with stealth patches) consistently received scores below PerfectDraft's threshold. But the reCAPTCHA check is score-based, not binary — a real user's browser session on the legitimate domain passes easily. The one-time setup cost of running a console command onperfectdraft.comis an acceptable UX trade-off for an integration that then runs autonomously forever.
Each of these observations was individually discoverable. The first required checking the web store's login page source. The second required decoding a JWT. The third required testing the web key against the API and understanding why the score mattered. But nobody had connected all three into a working auth flow — until now.