Google Local Tokens

0.7.6 · active · verified Thu Apr 16

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.

Common errors

```
ModuleNotFoundError: No module named 'glocaltokens'
```
cause The `glocaltokens` package is not installed in the current Python environment.

fix Run `pip install glocaltokens` in your active Python environment.
```
glocaltokens.exceptions.BadAuthenticationError: ...
```
cause Authentication failed with Google. Common reasons include incorrect username/password, 2-Factor Authentication not enabled, or Google blocking the login attempt.

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.
```
AttributeError: module 'protobuf.descriptor' has no attribute 'builder' (or similar protobuf related errors)
```
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.

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.

Warnings

breaking 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.
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.
gotcha 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.
Fix: Ensure your Python environment is version 3.9 or newer. Upgrade Python if necessary or switch to a compatible virtual environment.
gotcha 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`.
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.

Install

pip install glocaltokens Install with pip

Imports

GlocalTokens
```
from glocaltokens import GlocalTokens
```

BadAuthenticationError

from glocaltokens.exceptions import BadAuthenticationError

Quickstart

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).

import os
from glocaltokens import GlocalTokens, BadAuthenticationError

USERNAME = os.environ.get('GOOGLE_USERNAME', '')
PASSWORD = os.environ.get('GOOGLE_PASSWORD', '')

if not USERNAME or not PASSWORD:
    print("Please set GOOGLE_USERNAME and GOOGLE_PASSWORD environment variables.")
else:
    try:
        gt = GlocalTokens(USERNAME, PASSWORD)
        master_token = gt.get_master_token()
        print(f"Master Token: {master_token}")

        # Example: Get device tokens (requires a device to be connected/discovered)
        # device_tokens = gt.get_device_tokens()
        # print(f"Device Tokens: {device_tokens}")

    except BadAuthenticationError as e:
        print(f"Authentication failed: {e}")
        print("Ensure 2-Factor Authentication is enabled for your Google account.")
    except Exception as e:
        print(f"An unexpected error occurred: {e}")

view raw JSON →