Registry / auth-security / gpsoauth

gpsoauth

JSON →
library2.0.0pypypi✓ verified 84d ago

gpsoauth is a Python client library for Google Play Services OAuth, enabling Python applications to use the "master token" flow employed by Android devices for authenticating with Google services. This is particularly useful for projects that need to interact with Google APIs in a manner similar to Android apps. The current version is 2.0.0, and releases occur as needed to address changes in Google's authentication mechanisms or Python compatibility.

pip install gpsoauth
INSTALL
IMPORT
SIG · GPSOAUTH
G
gpsoauth
auth-securitypythonv2.0.0
Install
2.6s avg
Import
610ms
Disk
29MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v2.0.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.920 runs
installs and imports cleanly · install 0.0s · import 0.637s · 29.8MB
glibc
py 3.103.920 runs
installs and imports cleanly · install 2.6s · import 0.583s · 31MB
29MB installed
● package 29MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

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

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').")
Debug
Known issues
breakingVersion 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'`).
affects: >=2.0.0
breakinggpsoauth 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.
affects: >=2.0.0
gotchaWhen 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.
gotchaMany 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.
affects: All versions
Errors
Common errors & fixes
{'Error': 'BadAuthentication'}
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
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'}
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.
Upgrade
Version history
2.0.0latest on PyPI · released Jul 4, 2025
Audit
Dependencies
pycryptodomerequiredRequired for cryptographic operations to sign requests.
requestsrequiredUsed for making HTTP requests to Google's authentication endpoints.
urllib3requiredUsed by 'requests' and requires specific versions for compatibility with gpsoauth.
Agent activity
41 hits · last 30 days
node
32
Perplexity
1
OpenAI (training)
1
Resources
gpsoauth — pip install gpsoauth · libregistry