Headless implementation of Google web login (with support for 2-Step Verification) in Python


Join the chat at

Headless implementation of Google web login (with support for 2-Step Verification) in Python

py-google-auth exposes a high-level Python module and REST API that can be used for headless login on Google Accounts. The API supports 2-step verification if it is enabled on Google Account being used.

Note: This project is in "alpha" version right now. We are actively developing it and expect it to be beta-ready in next couple of weeks.



The license text is available in LICENSE file in root of this repo.


To install, run:

$ pip install py-google-auth

(for test):

$ pip install -i --extra-index-url py-google-auth

to update the version:

$ pip install -Ui --extra-index-url py-google-auth

To be able to make requests to API, you will need a token. You need to set it in your system environment for the API to access it and then pass it with every request you make:

export PY_GOOGLE_AUTH_TOKEN='some_token'

Also set a path for storing log files. These files will be created when ever some previously unhandled error will occur, in order to help debugging and fixing the problem. You can create a PR for such errors with the content of the file from your log path:

export PY_GOOGLE_AUTH_LOG_PATH=/path/to/logs/


Open your terminal and run:


This will start a gunicorn server, which will listen on localhost:8001 by default. You can change host and port (run py-google-auth -h for information).

Then you can make calls to the api using any HTTP library you like. The docs will contain examples with requests.

Example for an account without two factor auth enabled:

>>> import jsonpickle
>>> import os
>>> import requests

>>> token = os.environ.get('PY_GOOGLE_AUTH_TOKEN')
>>> data = {'email': '', 'password': 'myrandompassword', 'token': token}

>>> req ='http://localhost:8001/login', json=data)
>>> req
<Respose 200>

>>> session_str = req.json()['session']
>>> session = jsonpickle.decode(session_str)
>>> google_play_page = session.get('')
>>> google_play_page
<Respose 200>

Note: jsonpickle is used to encode python objects into json, since we get an encoded string which contains a request.Session object, we need to use decode to make it an object again.

More examples with other endpoints can be found in docs.

End points

Normal login (without two factor auth).

POST /login --data {'email': email, 'password': password, 'token': token}

If two factor auth is enabled, then next request should go here:

POST /step_two_login --data {'session': session, 'method': method, 'otp': otp, 'token': token}

If you want to use alternate method for two factor, use this before /step_two_login:

POST /change_method --data {'session': session, 'method': method, 'token': token}

Details about response data and status codes can be found in docs(writing soon).

Supported 2-step verification 'steps'

We support following 'steps' (i.e. methods) offered by Google in 2-step verification:

Unsupported 2-step verification 'step'

We DONT support following 'step' (i.e. method):


We are in process of writing documentation, which will be hosted at


To be done.


How to Contribute

  1. Check for open issues or open a fresh issue to start a discussion around a feature idea or a bug.
  2. Fork the repository on GitHub to start making your changes to the master branch (or branch off of it).
  3. Write a test which shows that the bug was fixed or that the feature works as expected.
  4. Send a pull request and poke the maintainer until it gets merged and published :)