Authentication and Authorization

The Python client library can be used to work with either public or private feeds, however the Documents List Data API only provides access to private feeds. That means your client application must send authenticated requests to the API. This can be done via ClientLogin username/password authentication, AuthSub, or OAuth.

Please see the Google Data APIs Authentication Overview for more information on AuthSub, OAuth, and ClientLogin.

Tip: The API supports SSL (HTTPS). If you’re using AuthSub/OAuth, make sure to specify a scope of http<strong>s</strong>://docs.google.com/feeds/ in order to request feeds over SSL. You can force all API requests to be over HTTPS by setting the DocsClient‘s ssl property: client.ssl = True.

AuthSub for web applications

AuthSub Authentication for Web Applications should be used by client applications which need to authenticate their users to Google or Google Apps accounts. The operator does not need access to the username and password for the Google Docs user - only an AuthSub token is required.

View instructions for incorporating AuthSub into your web application

Request a single-use token

When the user first visits your application, they need to authenticate. Typically, developers print some text and a link directing the user to the AuthSub approval page to authenticate the user and request access to their documents. The Google Data Python client library provides a function, generate_auth_sub_url() to generate this URL. The code below sets up a link to the AuthSubRequest page.

import gdata.gauth

def GetAuthSubUrl():
  next = 'http://www.example.com/myapp.py'
  scopes = ['http://docs.google.com/feeds/', 'https://docs.google.com/feeds/']
  secure = False  # set secure=True to request a secure AuthSub token
  session = True
  return gdata.gauth.generate_auth_sub_url(next, scopes, secure=secure, session=session)

print '<a href="%s">Login to your Google account</a>' % GetAuthSubUrl()

If you want to authenticate users on a Google Apps hosted domain, pass in the domain name to generate_auth_sub_url():

def GetAuthSubUrl():
  domain = 'example.com'
  next = 'http://www.example.com/myapp.py'
  scopes = ['http://docs.google.com/feeds/', 'https://docs.google.com/feeds/']
  secure = False  # set secure=True to request a secure AuthSub token
  session = True
  return gdata.gauth.generate_auth_sub_url(next, scopes, secure=secure, session=session, domain=domain)

The generate_auth_sub_url() method takes several parameters (corresponding to the query parameters used by the AuthSubRequest handler):

• the next URL — URL that Google will redirect to after the user logs into their account and grants access; http://www.example.com/myapp.py in the example above
• the scope — http://docs.google.com/feeds/ (and https://docs.google.com/feeds/) in the example above. Note, both are used as a convenience to your app. Later, if you decide to initiate API requests over SSL, your existing AuthSub tokens will be valid.
• secure, a boolean to indicate whether the token will be used in secure and registered mode or not; False in the example above
• session, a second boolean to indicate whether the single-use token will later be exchanged for a session token or not; True in the example above

Upgrading to a session token

See Using AuthSub with the Google Data API Client Libraries.

Retrieving information about a session token

See Using AuthSub with the Google Data API Client Libraries.

Revoking a session token

See Using AuthSub with the Google Data API Client Libraries.

Tip: Once your application has successfully acquired a long lived sessions token, store that token in your database to recall for later use. There’s no need to send the user back to AuthSub on every run of your application. Use client.auth_token = gdata.gauth.AuthSubToken(TOKEN_STR) to set an existing token on the client.

OAuth for web or installed/mobile applications

OAuth can be used as an alternative to AuthSub, and is intended for web applications. OAuth is similar to using the secure and registered mode of AuthSub in that all data requests must be digitally signed and you must register your domain.

View instructions for incorporating OAuth into your installed application

Fetching a request token

See Using OAuth with the Google Data API Client Libraries.

Authorizing a request token

See Using OAuth with the Google Data API Client Libraries.

Upgrading to an access token

See Using OAuth with the Google Data API Client Libraries.

Tip: Once your application has successfully acquired an OAuth access token, store that token in your database to recall for later use. There’s no need to send the user back through OAuth on every run of your application. Use client.auth_token = gdata.oauth.OAuthToken(TOKEN_STR, TOKEN_SECRET) to set an existing token on the client.

ClientLogin for installed/mobile applications

ClientLogin should be used by installed or mobile applications which need to authenticate their users to Google accounts. On first run, your application prompts the user for their username/password. On subsequent requests, an authentication token is referenced.

View instructions for incorporating ClientLogin into your installed application

To use ClientLogin, invoke the `ClientLogin() <http://gdata-python-client.googlecode.com/hg/pydocs/gdata.client.html#GDClient-ClientLogin>`_ method of DocsClient object, which is inherited from `GDClient <http://gdata-python-client.googlecode.com/hg/pydocs/gdata.client.html#GDClient>`_. Specify the email address and password of the user on whose behalf your client is making requests. For example:

client = gdata.docs.client.DocsClient(source='yourCo-yourAppName-v1')
client.ClientLogin('user@gmail.com', 'pa$$word', client.source);

Tip: Once your application has successfully authenticated the user for the first time, store the auth token in your database to recall for later use. There’s no need to prompt the user for his/her password on every run of your application. See Recalling an auth token for more information.

For more information on using ClientLogin in your Python applications, see the Using ClientLogin with the Google Data API Client Libraries.

Back to top