Diagnose your Play Console access with gplay auth doctor

Jul 5, 2026

Google Play API authentication is a small forest of things that can go wrong. Your service account might exist but not have the Android Publisher API enabled on its GCP project. It might be invited to your Play Console developer account but not accepted yet. Its key might be expired. Its scopes might be missing a permission you added recently.

Debugging any of these by hand is slow. gplay auth doctor runs every check in one shot.

What it checks

gplay auth doctor

Output (all-green case):

✓ Service account file readable at /Users/you/.gplay/keys/play-sa.json
✓ Service account email: play-cli@my-project.iam.gserviceaccount.com
✓ Client ID present
✓ Private key valid (RSA 2048)
✓ GCP project 'my-project' exists
✓ Android Publisher API enabled on my-project
✓ Reporting API enabled on my-project (needed for vitals)
✓ Service account accepted in Play Console developer account 4571234567890
✓ Developer role: Admin (Access all apps)
✓ Test API call: gplay apps list → 3 apps returned
✓ Configuration:
    default_package: com.example.app
    timeout: 120s
    upload_timeout: 5m

Everything looks good.

Any red or yellow line tells you exactly which step is broken. No more guessing.

Common failure modes

“Android Publisher API not enabled”

✗ Android Publisher API NOT enabled on my-project
  → Enable it: https://console.cloud.google.com/apis/library/androidpublisher.googleapis.com?project=my-project
  → Or run: gplay auth doctor --fix

--fix --confirm will call the GCP API to enable it for you:

gplay auth doctor --fix --confirm

Takes about 30 seconds to propagate.

“Service account not accepted in Play Console”

✗ Service account play-cli@my-project.iam.gserviceaccount.com found in Play Console
  invitation list but not accepted.
  → Open https://play.google.com/console/u/0/developers/4571234567890/users-and-permissions
    and click Accept next to this email.

This one is manual — Google requires a human accept the developer-account invite. gplay tells you exactly where to click.

“Developer role has insufficient permissions”

⚠ Developer role: Marketing (Access some apps)
  → Reason: your role can read listings but not tracks. Some gplay commands will fail.
  → Fix: escalate role in Play Console, or grant per-app permissions
    (gplay grants create --package com.example.app --permissions ...)

Some commands need admin, some need track edit. auth doctor flags the gap without waiting for a specific command to fail.

“Reporting API not enabled”

Only matters if you use gplay vitals:

⚠ Play Developer Reporting API NOT enabled — vitals commands will fail
  → Fix: gplay auth doctor --fix --confirm

“Private key expired or rotated”

✗ Private key rejected by Google (invalid_grant)
  → The key at /Users/you/.gplay/keys/play-sa.json is likely rotated or revoked
  → Fix: gplay auth login --service-account /path/to/new-key.json

You’ll see this the day someone in your org enforces the 90-day key rotation policy.

“Timeout too aggressive for uploads”

⚠ upload_timeout is 30s — AAB uploads over slow networks may fail
  → Recommended: 5m or higher via GPLAY_UPLOAD_TIMEOUT or ~/.gplay/config.yaml

Fix flags

--fix proposes remediations. --confirm executes them non-interactively (needed in CI). Together:

gplay auth doctor --fix --confirm

What --fix can do without asking:

Enable Android Publisher API on the linked GCP project.
Enable Play Developer Reporting API.
Update ~/.gplay/config.yaml timeouts to safer defaults.

What it won’t do (needs a human):

Accept a Play Console developer invitation (Google policy).
Rotate a service-account key (you should verify).
Escalate a developer role (permissions change).

CI usage

Run it as the first step of your release pipeline. If auth is degraded, fail early:

- name: Verify Play API auth
  env:
    GPLAY_SERVICE_ACCOUNT: ${{ secrets.PLAY_SA_JSON_PATH }}
  run: gplay auth doctor --output json | jq -e '.status == "healthy"'

--output json returns a structured verdict with per-check pass/fail. jq -e fails the step if the overall status isn’t healthy.

Beats a Play API call failing 20 minutes into an upload.

Alongside a new service account

The order of operations setup --auto runs, if you want to know what doctor is checking:

Detect or install gcloud.
Prompt for or create a GCP project.
Enable Android Publisher API and Reporting API on that project.
Create service account.
Download JSON key to ~/.gplay/keys/.
Print the service-account email and ask you to invite it in Play Console.

gplay auth doctor re-validates steps 3-6 any time you run it.

When to run it

After gplay setup --auto — sanity check.
When your CI job starts failing with invalid_grant or unauthorized.
After rotating a key.
After adding a new API (subscriptions → in-app products → reporting).
Weekly as a cron in a lightweight monitoring workflow.
Before assuming “gplay is broken” — it’s usually auth.

Getting started

brew install tamtom/tap/gplay
gplay setup --auto
gplay auth doctor

If you get a red line, read what it says — that’s where the fix is. If you’re not sure, gplay auth doctor --fix --confirm handles the fixable ones automatically. Full auth reference at /reference/auth/, full setup at /guides/authentication/.