Google Play Services OAuth Client

Common errors

• {'Error': 'BadAuthentication'}

  cause This is a common error indicating authentication failure. It often happens if the provided email/password (or app password) is incorrect, or if 2FA is enabled and a regular password is used instead of an app-specific password. Google's stricter security measures can also trigger this.
  fix 1. Verify your `email` and `password` (or `app_password`). 2. If 2FA is on, generate and use an App Password. 3. Consider trying the `exchange_token` flow as an alternative. 4. Ensure your Android ID is valid and consistent.

• Error: NeedsBrowser

  cause Google sometimes requires a browser-based sign-in for new devices or unusual activity, even with correct credentials, to verify identity. This prevents programmatic login.
  fix Try logging into the Google account in a web browser from the same network/IP address to clear any security prompts. If the issue persists, the `exchange_token` flow, where you manually obtain an `oauth_token` cookie after a browser login, might be the only workaround.

• {'Error': 'ServiceDisabled'}

  cause This error indicates that the Google service you are trying to access (specified by the `service` parameter in `perform_oauth`) is either disabled for the account or the request format is no longer accepted by Google.
  fix Check if the Google service is enabled for the account. Review the `gpsoauth` GitHub repository's issues or changelog for recent updates regarding `request format` changes that might address this error, as version 2.0.0 had an update to fix this issue for some services.

Warnings

• breaking Version 2.0.0 of gpsoauth raises the minimum supported Python version to 3.9. Projects using older Python versions must upgrade or stick to gpsoauth < 2.0.0.
  Fix: Upgrade your Python environment to 3.9 or higher. If unable to upgrade Python, pin gpsoauth to a version less than 2.0.0 (e.g., `pip install 'gpsoauth<2.0.0'`).
• breaking gpsoauth 2.0.0 introduced breaking changes related to urllib3 compatibility. It now explicitly supports `urllib3 > 2.0`, while older versions had compatibility fixes for `urllib3 < 2`.
  Fix: Ensure your `urllib3` dependency is version 2.0 or higher. If you encounter issues, verify the `requests` library (which depends on `urllib3`) is also updated to a compatible version.
• gotcha When 2-Factor Authentication (2FA) is enabled on your Google account, `perform_master_login` will often fail with a 'BadAuthentication' error if you use your regular Google account password. You need to generate and use an App Password instead.
• gotcha Many authentication failures (`BadAuthentication`, `NeedsBrowser`, `ServiceDisabled`) are due to Google's continuous changes to its authentication systems or stricter security checks. Sometimes, using the `exchange_token` flow with a manually obtained `oauth_token` cookie might be necessary.
  Fix: If `perform_master_login` fails, try the alternative flow documented in the `gpsoauth` README, which involves obtaining an `oauth_token` cookie from a browser session and using `gpsoauth.exchange_token`. Also, ensure the `client_sig` and `service` parameters for `perform_oauth` are correct for the target Google service.

Install

• pip install gpsoauth Install latest version

Imports

• gpsoauth

  import gpsoauth

• perform_master_login

  from gpsoauth import perform_master_login

• perform_oauth

  from gpsoauth import perform_oauth

• exchange_token

  from gpsoauth import exchange_token

Quickstart

This quickstart demonstrates how to perform a master login to obtain a master token, and then use that token to acquire a service-specific authentication token. It's crucial to use an App Password if Two-Factor Authentication (2FA) is enabled on the Google account. Sensitive credentials are retrieved from environment variables for better security.

import os
import gpsoauth

# It's recommended to retrieve these from environment variables or a secure configuration.
# For a real application, avoid hardcoding sensitive data.
email = os.environ.get('GPSOAUTH_EMAIL', 'your_email@gmail.com')
password = os.environ.get('GPSOAUTH_PASSWORD', 'your_app_password') # Use an app password if 2FA is enabled
android_id = os.environ.get('GPSOAUTH_ANDROID_ID', '0123456789abcdef') # A 16-character hex device ID

try:
    # Perform master login to get the master token
    master_response = gpsoauth.perform_master_login(
        email=email,
        password=password,
        android_id=android_id
    )
    master_token = master_response.get('Token')

    if master_token:
        print(f"Master Token: {master_token[:10]}...")

        # Example: Perform OAuth for Google Play Music service ('sj')
        auth_response = gpsoauth.perform_oauth(
            email=email,
            master_token=master_token,
            android_id=android_id,
            service='sj', # Example service: Google Play Music
            app='com.google.android.music',
            client_sig='38918a453d07199354f8b98840b6156e19f7dc9f' # Example signature for Google Play Music
        )
        auth_token = auth_response.get('Auth')

        if auth_token:
            print(f"Service Auth Token: {auth_token[:10]}...")
        else:
            print(f"Could not get service auth token. Response: {auth_response}")

    else:
        print(f"Could not get master token. Response: {master_response}")

except Exception as e:
    print(f"An error occurred: {e}")
    print("Ensure your email, password (or app password), and Android ID are correct.")
    print("If 2-Factor Authentication is enabled, use an App Password instead of your Google account password.")
    print("Also, check if your Google account requires a browser sign-in ('NeedsBrowser' error) or if the service is disabled ('ServiceDisabled').")