My favorites | English | Sign in

Accounts APIs

OAuth API Reference

Google supports the OAuth protocol for authorizing web or installed applications that access their users' Google services. This page describes Google's implementation of the OAuth open standard for authorization. For more information on OAuth, see the OAuth.net documentation. Web applications making OAuth requests to Google can be registered or unregistered, and must sign all requests.

For help using the Google OAuth API, see:

See also the Google Accounts API Group for discussion on using the Accounts API. For information on Google's other account authorization solutions, see the Getting Started guide.

Contents

  1. OAuth endpoints
    1. OAuthGetRequestToken
    2. OAuthAuthorizeToken
    3. OAuthGetAccessToken
  2. Signing requests
  3. Handling users with multiple accounts
  4. Testing and debugging OAuth requests
  5. Revoking an OAuth access token

OAuth endpoints

The following methods make up Google's OAuth endpoints:

Version Update: OAuth v1.0 to OAuth v1.0a

Google's OAuth endpoints are now updated for OAuth v1.0a. This update involves two major changes:

  • A new parameter, oauth_verifier, is now required by the OAuthGetAccessToken endpoint. This parameter takes a verification code, which is generated by Google once a user has granted access to the third-party application. The verification code is returned one of two ways:
    • If the third-party application supplies a callback URL, Google redirects the user back to the application after a successful call to OAuthAuthorizeToken, with query parameters containing token, token secret, and verifier.
    • If the third-party application does not supply a callback URL, Google displays a web page to the user containing the verification code. This scenario allows applications that can't process redirects to use this OAuth; it is assumed that these applications will provide a way for users to enter the verification code into the application.
  • The parameter oauth_callback has been moved from the OAuthAuthorizeToken endpoint to the OAuthGetRequestToken endpoint. This enables authorization providers, like Google, to confirm that a URL redirect back to the third-party application can be handled.

For backward compatibility, Google continues to support applications using OAuth version 1.0, recognizing calls to OAuthAuthorizeToken with the oauth_callback parameter and calls to OAuthGetAccessToken without a verification code. Because of the lack of a verification code, however, applications using v1.0 will trigger the yellow warning box displayed to users on the Request Access page (see example).

OAuthGetRequestToken

Contact Google for a request token. Google verifies that the requesting application has been registered with Google or is using an approved signature (in the case of installed applications). The request token acquired with this request must be first authorized by the end user and then exchanged for an access token. A request token cannot be used to get access to a Google service.

Send a request to: https://www.google.com/accounts/OAuthGetRequestToken with the following query parameters:

Parameter Description
oauth_consumer_key (required) Domain identifying the third-party web application. This is the domain used when registering the application with Google.
oauth_nonce (required) Random 64-bit, unsigned number encoded as an ASCII string in decimal format. The nonce/timestamp pair should always be unique to prevent replay attacks.
oauth_signature_method (required) Signature algorithm. The legal values for this parameter "RSA-SHA1" or "HMAC-SHA1". Google does not support "PLAINTEXT".
oauth_signature (required) String generated using the referenced signature method. See Signing requests.
oauth_timestamp (required) Integer representing the time the request is sent. The timestamp should be expressed in number of seconds after January 1, 1970 00:00:00 GMT.
scope (required) URL identifying the service(s) to be accessed. The resulting token enables access to the specified service(s) only. Scopes are defined by each Google service; see the service's documentation for the correct value. To specify more than one scope, list each one separated with a space. This parameter is not defined in the OAuth standards; it is a Google-specific parameter.
oauth_callback (optional) URL the user should be redirected to after access to a Google service(s) is granted (in response to a call to OAuthAuthorizeToken). The response to this OAuthGetRequestToken call verifies that Google handles a callback URL. The callback URL can include url-encoded query parameters. To trigger an alternative sequence, in which Google displays a success page with a verification code that the user must then supply to the third-party application, use the value "oob". In the subsequent call to OAuthGetAccessToken, the parameter verifier must be set to this value.
oauth_version (optional) The OAuth version used by the requesting web application. This value must be "1.0"; if not provided, Google assumes version 1.0 is in use.
xoauth_displayname (optional) String identifying the application. This string is displayed to end users on Google's authorization confirmation page. For registered applications, the value of this parameter overrides the name set during registration and also triggers a message to the user that the identity can't be verified. For unregistered applications, this parameter enables them to specify an application name, In the case of unregistered applications, if this parameter is not set, Google identifies the application using the URL value of oauth_callback; if neither parameter is set, Google uses the string "anonymous".

Depending on the type of request sent, these parameters can be placed in:

  • Authorization header of a GET or POST request. Use "Authorization: OAuth". All parameters listed above can go in the header, except for scope and xoauth_displayname, which must go either in the body or in the URL as a query parameter. The example below puts them in the body of the request.
  • Body of a POST request. The content type must be "Content-Type: application/x-www-form-urlencoded".
  • As URL query parameters in a GET request.

For more details, see the OAuth specification, Section 5.2.

Sample request

This example illustrates a registered web application asking for a request token to access a user's Calendar and Picasa accounts.

POST /accounts/OAuthGetRequestToken HTTP/1.1
Host: https://www.google.com
Content-Type: application/x-www-form-urlencoded
Authorization: OAuth
oauth_consumer_key="yourwebapp.com",
oauth_signature_method="RSA-SHA1",
oauth_signature="wOJIO9A2W5mFwDgiDvZbTSMK%2FPY%3D",
oauth_timestamp="137131200",
oauth_nonce="4572616e48616d6d65724c61686176",
oauth_version="1.0"
oauth_callback="http://www.yourwebapp.com/showcalendar.html"

scope="http://www.google.com/calendar/feeds http://picasaweb.google.com/data"

Request token response

If the request for a request token is successful, Google responds with an HTTP 200 OK message containing an OAuth request token, a token "secret", and confirmation that Google handles a callback URL.

A token request may be rejected by Google if the request is malformed or if Google has reason to believe the requestor is not acting in good faith. If the request is not successful, Google returns the following error:

  • HTTP 400 Bad Request: in the case of an unsupported or missing parameter, an unsupported oauth_signature_method, or other error in the request format or content.

Sample response

This example illustrates an OAuth request token returned in the response header. At this point, the request token cannot be used to request data from the Google service; it must be authorized by the Google Authorization service.

oauth_token=ab3cd9j4ks73hf7g&oauth_token_secret=ZXhhbXBsZS5jb20&oauth_callback_confirmed=true

OAuthAuthorizeToken

Call the Google Authorization service at https://www.google.com/accounts/OAuthAuthorizeToken with the following query parameters:

Parameter Description
oauth_token (required) Request token obtained from Google.
hd (optional) String value identifying a particular hosted domain account to be accessed (for example, 'mycollege.edu'). Use "default" to specify a regular Google account ('username@gmail.com'). This is a Google-specific parameter.
hl (optional) An ISO 639 country code identifying what language the approval page should be translated in (for example, 'hl=en' for English). The default is the user's selected language. This is a Google-specific parameter.
btmpl (optional) Forces a mobile version of the approval page. The only accepted value is "mobile". This is a Google-specific parameter.

Sample request

This example shows a request for authorization:

GET https://www.google.com/accounts/OAuthAuthorizeToken?oauth_token=ab3cd9j4ks73hf7g&hd=mycollege.edu&hl=en&btmpl=mobile

Request authorization response

If Google accepts the request, the user is redirected to a Google login page, where:

  1. The user is asked to verify access to their Google account. Because it's possible for someone to have more than one Google-affiliated account (a regular Google account and one or more hosted accounts), in some cases the user also must specify which account to grant access to. There are two possible paths your users may experience:
    • If you've used the hd parameter to specify an account domain, the user is asked to log in to that account, if they aren't already logged in. For more information on the hd parameter, see Handling users with multiple accounts.
    • If you don't use the hd parameter, the user is put into a "universal login" path, which walks the user through selecting and logging into any type of Google account. Because the universal login process is still in beta, we recommend you use the hd parameter whenever possible. We're continuing to improve the user experience in this area.
  2. Once the user has selected an account and verified access, the Authorization service displays the Google Access Request page (see example). This page:
    • Identifies the third-party application requesting access. By default, Google uses the value of xoauth_displayname in the initial OAuthGetRequestToken request and displays a message indicating that the application's identity cannot be verified. If no display name is specified and the application is registered with Google, Google uses the name specified during registration. If the application is not registered, Google uses the oauth_callback URL, if set; if it is not set, Google uses the string "anonymous".
    • Informs the user that a third party wants access to their Google service.
    • Identifies the Google service(s) to be accessed.
    • Prompts the user to confirm that it's OK to give the third party access to their Google service.
  3. If the user grants access, the referenced request token is authorized.
  4. If a callback URL is provided, Google redirects the user to the URL specified in the web application registration, and the request token and verification number are included as query parameters. If no callback URL is provided, Google displays a message to the user with a verification code (see example).

Note: The return of a verification code does not indicate that a request token has been authorized. If a request token has not been authorized, then requests to exchange it for an access token will fail.

Sample response

This example illustrates the format of a Google redirect back to the web application with a request token and verification code. The token is a text string, up to 256 bytes.

http://www.yourwebapp.com/showcalendar.html?oauth_token=CKF50YzIHxCT85KMAg&oauth_verifier=fERNOO3NfWph90CPCeIutmFA

Google redirects with token and verifier regardless of whether the token has been authorized.

OAuthGetAccessToken

Contact Google to exchange an authorized request token for an access token. The access token received in response to this request is used to request data from a Google service.

Send an HTTP request to: https://www.google.com/accounts/OAuthGetAccessToken with the following query parameters:

Parameter Description
oauth_consumer_key (required) Domain identifying the third-party web application. This is the domain used when registering the application with Google. This value must be the same as the one provided in OAuthGetRequestToken.
oauth_token (required) Authorized request token.
oauth_verifier (required) Verification code issued by Google in response to a successful call to OAuthAuthorizeToken. The verification code is either returned as a query parameter in the redirect URL or is displayed in a web page shown to the user once access has been granted, which the user must supply to the application in some way.
oauth_signature_method (required) Signature algorithm. The legal values for this parameter "RSA-SHA1" or "HMAC-SHA1". Google does not support "PLAINTEXT".
oauth_signature (required) String generated using the referenced signature method. See Signing requests.
oauth_timestamp (required) Integer representing the time the request is sent. The timestamp should be expressed in number of seconds after January 1, 1970 00:00:00 GMT.
oauth_nonce (required) Random 64-bit, unsigned number encoded as an ASCII string in decimal format. The nonce/timestamp pair should always be unique to prevent replay attacks.
oauth_version (optional) The OAuth version used by the requesting web application. This value must be "1.0"; if not provided, Google assumes version 1.0 is in use.

Depending on the type of request sent, these parameters can be placed in:

  • Authorization header of a GET or POST request. Use "Authorization: OAuth".
  • Body of a POST request. The content type must be "Content-Type: application/x-www-form-urlencoded".
  • URL query part of a GET request.

For more details, see the OAuth specification, Section 5.2.

Sample request

This example illustrates a web application requesting an access token. 

POST /accounts/OAuthGetAccessToken HTTP/1.1
Host:  https://www.google.com
Content-Type: application/x-www-form-urlencoded
Authorization: OAuth
oauth_consumer_key="example.com",
oauth_token="CKF50YzIHxCT85KMAg",
oauth_verifier="fERNOO3NfWph90CPCeIutmFA",
oauth_signature_method="RSA-SHA1",
oauth_signature="wOJIO9A2W5mFwDgiDvZbTSMK%2FPY%3D",
oauth_timestamp="137131200",
oauth_nonce="4572616e48616d6d65724c61686176",
oauth_version="1.0"

Note: The Authorization should be contained on a single line. Newlines have been inserted for clarity.

Access token response

If the request for an access token is successful, Google responds with an HTTP 200 OK message containing an OAuth access token and a token "secret".

A token request may be rejected by Google if the request is malformed or if Google has reason to believe the requestor is not acting in good faith. If the request is not successful, Google returns the following error:

  • HTTP 400 Bad Request:in the case of an unsupported or missing parameter, an unsupported signature method, or other error in the request format or content. This error is also returned if the referenced request token has not been authorized.

Sample response

This example illustrates an OAuth access token returned in the response header.

oauth_token=ab3cd9j4ks73hf7g&oauth_token_secret=ZXhhbXBsZS5jb20

Signing OAuth requests

All calls requesting or using an OAuth token must be signed, regardless of whether your application is registered with Google or not. This includes calls to OAuthGetRequestToken, OAuthGetAccessToken, and all requests made to Google services. This section describes how to generate a signature for the requests. For more detailed information on this process, see the OAuth specification, Section 9.

Each request must specify the signature method in use (oauth_signature_method). Unregistered applications should use HMAC-SHA1. Registered applications can use either RSA-SHA1 and HMAC-SHA1.

  1. Construct a signature "base string", which consists of a concatenation of three request elements:
    • The HTTP request method.
    • The base URL the request is being sent to. This URL should not include any query parameters. When signing calls to Google services, refer to the OAuth specification, Section 9.1.2, for relevant instructions.
    • A normalized string of the parameters in the request (excluding the oauth_signature parameter). This includes parameters sent in the request header or body, as well as query parameters added to the request URL. To normalize the string, sort the parameters using lexicographical byte value ordering. For more details on normalizing this string, see Section 9.1.1 of the OAuth specification.
  2. Generate an oauth_signature using one of the following sequences:
    • If your application is not registered, select HMAC-SHA1 and use the following key and secret:
      consumer key: "anonymous"
      consumer secret: "anonymous"
    • If your application is registered and you're using RSA-SHA1, use the private key corresponding to the certificate uploaded to Google during registration.
    • If your application is registered and you're using HMAC-SHA1, use the OAuth "consumer secret" value generated during registration; this value is displayed on your domain's registration page.

Example requests

This example shows a registered application using the Google Calendar API to retrieve a user's list of calendars at http://www.google.com/calendar/feeds/default/allcalendars/full?orderby=starttime. The example assumes you have a valid OAuth access token.

Signature base string:

GET&http%3A%2F%2Fwww.google.com%2Fcalendar%2Ffeeds%2Fdefault%2Fallcalendars%2Ffull&oauth_consumer_key%3Dexample.com%26oauth_nonce%3D4572616e48616d6d65724c61686176%26oauth_signature_method%3DRSA-SHA1%26oauth_timestamp%3D137131200%26oauth_token%3D1%252Fab3cd9j4ks73hf7g%26oauth_version%3D1.0%26orderby%3Dstarttime

Notice the orderby=starttime query parameter is ordered along with the rest of the oauth_* parameters in the base string.

HTTP Request:

GET /calendar/feeds/default/allcalendars/full?orderby=starttime HTTP/1.1
Host:  http://www.google.com
Content-Type: application/atom+xml
Authorization: OAuth
oauth_token="1%2Fab3cd9j4ks73hf7g",
oauth_signature_method="RSA-SHA1",
oauth_signature="wOJIO9A2W5mFwDgiDvZbTSMK%2FPY%3D",
oauth_consumer_key="example.com",
oauth_timestamp="137131200",
oauth_nonce="4572616e48616d6d65724c61686176",
oauth_version="1.0"

Note: The Authorization should be contained on a single line. Newlines have been inserted for clarity only. The ordering of the oauth_* parameters does not matter in the Authorization header.

Handling users with multiple accounts

In most cases, the process of getting access confirmation from an end user is a simple matter of the user logging into their account and choosing whether or not to grant access. For users who have more than one Google Account, however, (a regular Google account and/or one or more hosted accounts), users may need to follow additional "universal login" steps to identify which account they wish to grant access to.

In certain circumstances, using the hd parameter with OauthAuthorizeToken can help streamline your users' experience. If your application is designed for one particular managed domain, you can eliminate the extra login steps by using this parameter to specify the only domain that's valid for your application. You can also use the hd parameter if your application accesses services that are not available to hosted accounts; setting the value to 'default' will limit authorization to regular accounts only. Using this parameter helps limit the account choices for the user, preventing them from making invalid choices.

Testing and debugging OAuth requests

Google's OAuth Playground tool helps to debug problems, check your own implementation, and experiment with the Google Data APIs.

  • Illustrates the OAuth authorization flow:
    • Fetches a request token
    • Authorizes a request token
    • Upgrades the token to an access token.
  • Helps with debugging OAuth requests:
    • Displays the correct signature base string for each request.
    • Displays the correct Authorization header for each request.
    • Demonstrates how to use an oauth_token to interact with an authorized Google Data feed.
    • Tests your own oauth_consumer_key (your registered domain), RSA private key, and HMAC consumer secret.
  • Lets you experiment with the Google Data APIs:
    • Uses GET, PUT/POST, or DELETE to manipulate data.
    • Allows you to view an authorized feed directly in your browser.
    • Identifies what Data feeds are available to your oauth_token.

More debugging tips are available in Using OAuth with the Google Data APIs.

Revoking an OAuth access token

OAuth access tokens can be revoked either manually or programmatically.

Manually revoking a token (for Google account holders)

  1. Users can make changes to their Google Accounts settings at https://www.google.com/accounts/. For Google Apps (hosted) domain accounts, go to https://www.google.com/a/yourdomain.com/ManageAccount.
  2. Click the link "Change authorized websites".
  3. In the list of authorized domains displayed, locate the domain to be revoked. Click the "Revoke Access" link next to the domain name.

Access to the user account for that domain will no longer be allowed. Users must explicitly approve subsequent access requests, using the same process as they originally granted access.

Programmatically revoking a token (for third-party applications)

To programmatically revoke a token, send a request to AuthSub's AuthSubRevokeToken endpoint with the necessary signed OAuth request.