{"id":9015,"library":"glocaltokens","title":"Google Local Tokens","description":"glocaltokens is a Python library designed to extract Google device local authentication tokens, primarily for use in headless systems. It handles the authentication flow using a Google username and password to obtain master tokens, which can then be used to retrieve device-specific tokens. The current version is 0.7.6, and the project maintains an active release cadence, frequently updating dependencies and introducing minor enhancements.","status":"active","version":"0.7.6","language":"en","source_language":"en","source_url":"https://github.com/leikoilja/glocaltokens","tags":["google","authentication","tokens","smart home","headless","2fa"],"install":[{"cmd":"pip install glocaltokens","lang":"bash","label":"Install with pip"}],"dependencies":[{"reason":"Required for Google Play Services authentication to obtain master tokens.","package":"gpsoauth"},{"reason":"Handles protobuf definitions and API interactions for Google Home devices.","package":"ghome-foyer-api"},{"reason":"Indirectly required by ghome-foyer-api; version compatibility is crucial.","package":"protobuf"}],"imports":[{"symbol":"GlocalTokens","correct":"from glocaltokens import GlocalTokens"},{"symbol":"BadAuthenticationError","correct":"from glocaltokens.exceptions import BadAuthenticationError"}],"quickstart":{"code":"import os\nfrom glocaltokens import GlocalTokens, BadAuthenticationError\n\nUSERNAME = os.environ.get('GOOGLE_USERNAME', '')\nPASSWORD = os.environ.get('GOOGLE_PASSWORD', '')\n\nif not USERNAME or not PASSWORD:\n    print(\"Please set GOOGLE_USERNAME and GOOGLE_PASSWORD environment variables.\")\nelse:\n    try:\n        gt = GlocalTokens(USERNAME, PASSWORD)\n        master_token = gt.get_master_token()\n        print(f\"Master Token: {master_token}\")\n\n        # Example: Get device tokens (requires a device to be connected/discovered)\n        # device_tokens = gt.get_device_tokens()\n        # print(f\"Device Tokens: {device_tokens}\")\n\n    except BadAuthenticationError as e:\n        print(f\"Authentication failed: {e}\")\n        print(\"Ensure 2-Factor Authentication is enabled for your Google account.\")\n    except Exception as e:\n        print(f\"An unexpected error occurred: {e}\")","lang":"python","description":"This quickstart demonstrates how to instantiate GlocalTokens, obtain a master token using environment variables for credentials, and print it. It includes basic error handling for authentication failures and advises on 2FA. Obtaining device-specific tokens requires additional setup and discovery (commented out)."},"warnings":[{"fix":"Use a dedicated virtual environment. If protobuf conflicts persist, ensure no other packages pin a conflicting protobuf version. Consider using `pip install --no-deps glocaltokens` and manually installing compatible versions of `gpsoauth` and `ghome-foyer-api` if advanced control is needed, though this is rarely necessary.","message":"The library's internal dependencies, particularly `gpsoauth` and `ghome-foyer-api` (which wraps `protobuf`), have seen significant version bumps. Upgrading `glocaltokens` may require a fresh environment or careful dependency resolution to avoid conflicts with other libraries using older `gpsoauth` or `protobuf` versions.","severity":"breaking","affected_versions":">=0.7.0 (protobuf changes), >=0.7.6 (gpsoauth 2.0.0)"},{"fix":"Ensure your Python environment is version 3.9 or newer. Upgrade Python if necessary or switch to a compatible virtual environment.","message":"As of v0.6.9, `glocaltokens` requires Python 3.9 or higher. Attempts to install or run the library on older Python versions will fail.","severity":"gotcha","affected_versions":">=0.6.9"},{"fix":"Enable 2-Factor Authentication on the Google account you are using. This typically involves setting up a phone or authenticator app. Ensure the username and password are correct.","message":"Google accounts used for authentication generally require 2-Factor Authentication (2FA) to be enabled for `get_master_token()` to succeed, especially in headless or automated environments. Without 2FA, you might encounter `BadAuthenticationError`.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Run `pip install glocaltokens` in your active Python environment.","cause":"The `glocaltokens` package is not installed in the current Python environment.","error":"ModuleNotFoundError: No module named 'glocaltokens'"},{"fix":"Verify your Google username and password are correct. Enable 2-Factor Authentication on your Google account. If issues persist, try logging into Google with the same credentials in a web browser to check for any security prompts.","cause":"Authentication failed with Google. Common reasons include incorrect username/password, 2-Factor Authentication not enabled, or Google blocking the login attempt.","error":"glocaltokens.exceptions.BadAuthenticationError: ..."},{"fix":"Use a fresh virtual environment. If the issue persists, try `pip install --upgrade protobuf` to get the latest compatible version, or `pip uninstall protobuf` followed by `pip install glocaltokens` to allow `glocaltokens` to install its preferred version.","cause":"This typically indicates an incompatibility between the `protobuf` version installed and the version expected by `ghome-foyer-api` (a dependency of `glocaltokens`), or another library in your environment is pinning an incompatible `protobuf` version.","error":"AttributeError: module 'protobuf.descriptor' has no attribute 'builder' (or similar protobuf related errors)"}]}