Google Play authentication

Morphe Builder delegates Google Play protocol handling to the pinned goopdl CLI. Account credentials are optional but recommended for reliable local and CI downloads.

Access modes

Mode	Configuration	Behavior
Account-backed	GOOPDL_ACCOUNT_EMAIL and GOOPDL_AAS_TOKEN	Direct Google check-in, device configuration, and temporary bearer-token exchange. No anonymous dispenser is contacted.
Anonymous	Neither account variable	Uses MORPHE_DISPENSER_URL or the built-in public dispenser.
Invalid partial setup	Only one account variable	Fails closed instead of silently downgrading to anonymous access.

Anonymous access is frequently blocked or rate-limited from datacenter and GitHub-hosted runner IP ranges. Configure verified fallback providers even when account-backed access is enabled.

Generate an AAS token

morphe-builder aastoken delegates token generation to pinned goopdl, inherits its interactive input and output, and never captures the token. It does not create credentials.txt or token.txt.

Browser OAuth mode

Browser OAuth is recommended because Google commonly rejects account passwords and app passwords with BadAuthentication:

morphe-builder aastoken --browser

Sign in and select I agree in the isolated Chrome, Edge, Chromium, or Brave window. Pinned goopdl captures the signed-in email and one-time oauth_token, deletes the temporary browser profile, and prints the resulting persistent AAS token. Set GOOPDL_BROWSER to the browser executable when automatic detection fails.

No local CLI or Termux

goopdl-auth is an alternative for users who do not have a computer or do not want to run Morphe Builder, goopdl, or Termux locally. Use its instructions to create credentials, then configure GOOPDL_ACCOUNT_EMAIL and GOOPDL_AAS_TOKEN as below. Treat its resulting AAS token with the same password-equivalent handling described in this guide.

Manual OAuth mode

When browser automation is unavailable:

morphe-builder aastoken --oauth

1. Open Google EmbeddedSetup.
2. Sign in and select I agree.
3. Open browser developer tools.
4. In Chrome or Edge, open Application → Cookies → https://accounts.google.com.
5. Copy the oauth_token cookie value. It starts with oauth2_4/.
6. Run morphe-builder aastoken --oauth, enter the same email, and paste the token when prompted.

The one-time OAuth token is short-lived and single-use. The resulting persistent token must start with aas_et/.

A value starting with g.a is a temporary bearer token, not an AAS token. Do not store or configure it as GOOPDL_AAS_TOKEN.

Configure locally

Set both variables in the process environment before running auth, download, or build:

export GOOPDL_ACCOUNT_EMAIL='account@example.com'
export GOOPDL_AAS_TOKEN='aas_et/...'
morphe-builder auth --arch arm64

PowerShell:

$env:GOOPDL_ACCOUNT_EMAIL = 'account@example.com'
$env:GOOPDL_AAS_TOKEN = 'aas_et/...'
morphe-builder auth --arch arm64

auth prepares reusable Google Play session state in the platform cache, outside the repository. Use --arch both when both ARM64 and ARMv7 downloads are needed.

Do not persist credentials in shell history, .env files committed to Git, TOML, command arguments, authenticated URLs, build output, or provenance.

Configure GitHub Actions

Create environment secrets under Settings → Environments → release → Environment secrets:

Secret	Value
GOOPDL_ACCOUNT_EMAIL	Dedicated Google account email.
GOOPDL_AAS_TOKEN	Persistent token starting with aas_et/.

Both release workflows read credentials from the protected release environment. Pull-request CI receives no Google Play credentials and performs no live download.

After adding both secrets, run Manual verified build or wait for Daily verified update. See CI and releases for workflow and secret boundaries.

Credential handling rules

Treat the AAS token as a password-equivalent persistent credential:

• use a dedicated Google account
• keep 2-Step Verification enabled
• store local values only in an appropriate secret manager or process environment
• store CI values only as protected GitHub Environment secrets
• never include credentials in caches, artifacts, logs, screenshots, issue reports, or provenance
• rotate the token after suspected exposure

Changing the Google account password invalidates the AAS token.

Anonymous dispenser

Without account variables, auth and download use MORPHE_DISPENSER_URL or the built-in dispenser:

export MORPHE_DISPENSER_URL='https://dispenser.example.invalid'
morphe-builder auth --arch arm64

A dispenser URL must use HTTPS and contain no embedded credentials, query string, or fragment. Account-backed authentication always bypasses it.

HTTP 403 or 429 from anonymous infrastructure means access is unavailable or rate-limited. Use account-backed credentials or let a configured verified provider fallback handle the requested version.

Safe diagnostics

Morphe Builder removes URL query strings and fragments from errors and redacts values associated with authorization, cookie, token, password, and dispenser.

Before sharing a failure report, still inspect output manually. Never paste environment dumps, browser cookies, complete authenticated URLs, or raw goopdl debug output containing credentials.