OAuth 1.0 API Reference

Important: OAuth 1.0 was officially deprecated on April 20, 2012, and is no longer supported.
We encourage you to migrate to OAuth 2.0 as soon as possible.

The first section in this document describes how to migrate your code from
OAuth 1.0 to OAuth 2.0. The rest of the document describes Google's implementation of the deprecated
OAuth 1.0 open standard
for authorization, and explains how to implement OAuth 1.0 in an application.

Migrating from OAuth 1.0 to OAuth 2.0

Important: OAuth 1.0 is
deprecated, and we encourage you to migrate
to OAuth 2.0 as soon as possible.
To get help on Stack Overflow,
tag your questions with 'google-oauth'.

This section describes how to migrate your application from
OAuth 1.0 to OAuth 2.0, without end-user
intervention. After migration, your application can stop using the OAuth 1.0 library and can
access resources using OAuth 2.0 tokens.

If you are unsure whether you are using OAuth 1.0, complete the following
steps:

You present both the OAuth 1.0 and OAuth 2.0 credentials in a single request; there is no other
binding of the two grants. The idea is to exchange an OAuth 1.0 grant for an OAuth 2.0 refresh
token. The basic flow is shown in the following figure.

As soon as your application obtains the OAuth 2.0 access token, it can drop the OAuth 1.0 token
and use OAuth 2.0 tokens to access users' resources.

Sending a migration request

You send a grant migration request to the existing Google OAuth 2.0 token endpoint, which is
https://www.googleapis.com/oauth2/v3/token.
The request must be a POST,
and you must send it via HTTPS. The endpoint refuses HTTP
requests.

Signed-request flow for migration

Request

The request is a signed OAuth 1.0 request with additional OAuth 2.0 request parameters. You
include the OAuth 1.0 consumer key, token secret, and signature in the OAuth 1.0 authorization
HTTP header. For example:

Optional. Use the scope parameter when you want to "down-scope" and
request fewer OAuth 2.0 scopes than were granted via OAuth 1.0. List the requested scopes in the
scope parameter, separated by spaces. Any other scopes are dropped, and
the requested scopes are validated. If you do not provide the
scope parameter, the requested scopes are
those previously granted via OAuth 1.0.

An example request follows — be sure to replace YOUR_CLIENT_SECRET
with your value of client_secret.

Response

After a migration request is validated, your application is issued a refresh token with
down-scoped scopes. The response body is in JSON format, and it contains only an OAuth 2.0
refresh token (no access token).

Obtaining an OAuth 2.0 access token

It is the responsibility of your client software to store the
refresh token permanently and securely.

Note: When the refresh token is used,
the OAuth 1.0 access token will expire in 1 hour.

Unsigned-request flow for migration

If you have a native application and do not want to sign the
request, you can use a no-signature flow. In this flow, your application sends all the necessary credentials in the request parameters
over SSL. No authorization header is needed in this case. This also allows native
applications to drop OAuth 1.0 libraries, either immediately or in a future version,
and still have an upgrade path.

Note: In the unsigned-request flow, the OAuth 1.0 access token
is revoked immediately after a refresh token is issued. This flow is allowed
only for native applications.
Requests from web applications that use this flow are denied.

Request

In an unsigned-request flow, include the following OAuth 2.0 parameters in your request:

grant_type=urn:ietf:params:oauth:grant-type:migration:oauth1

client_id

client_secret

scope

The rules governing the parameters, and their meanings, are identical to those in the
signed-request flow.

Also include the following OAuth 1.0 parameters:

oauth_consumer_key

oauth_consumer_secret

oauth_token

oauth_token_secret

An example request follows — be sure to replace YOUR_TOKEN_SECRET
and YOUR_CLIENT_SECRET with your values of
oauth_token_secret and client_secret

As in the signed-request flow, the response is a refresh token.
(For details, see Response).

Validations that are performed on migration requests

When you migrate your code from OAuth 1.0 to OAuth 2.0 and you send a
migration request to Google’s OAuth 2.0
token endpoint, all credentials presented in the request are validated.

In addition, scope validation is performed after down-scoping.
None of the following are allowed in the list of requested scopes:

An empty scope list

Any scopes that were not previously granted via OAuth 1.0

https://www.google.com/accounts/OAuthLogin

https://www.googleapis.com/auth/plus.login

After you migrate your apps to OAuth 2.0, see Using
OAuth 2.0 to Access Google APIs for information about using the OAuth 2.0 authorization protocol
to access Google APIs and request access to data associated with a user's Google Account.
To get help on Stack Overflow,
tag your questions with 'google-oauth'.

If you provide a “sign-in with Google” feature, we recommend using Google+ Sign-In,
which is built on the OAuth 2.0 and OpenID Connect protocols.

In the Create service account window, type a name for the service
account, and select Furnish a new private key and Enable Google
Apps Domain-wide Delegation.
Then click Create.

Your new public/private key pair is generated and downloaded to your machine;
it serves as the only copy of this key. You are responsible for storing it
securely.

Your new service account's client ID, email address, and private key are
used in the OAuth 2.0 flow instead of your app's consumer key and consumer
secret, which were used in the OAuth 1.0 flow.

The administrator of the Apps domain that runs your app must add your
service account's client ID on the Manage API client access page
instead of consumer key that was used for the OAuth 1.0 flow. See Managing API client
access.

When your app makes authorized API calls, use the OAuth 2.0 service account
flow instead of the OAuth 1.0 flow. See the
OAuth
2.0 service account documentation.

The major differences between the OAuth 2.0 flow and OAuth 1.0 flow are:

Rather than send your consumer key and signature (and other values)
together with your API call, as in the OAuth 1.0 flow, you instead
create a signed JSON web token (JWT) that contains your service account
email address (and other values), exchange the JWT for an access token,
and send the access token together with your API call.

Rather than specify the user to act as using the
xoauth_requestor_id parameter, as in the OAuth 1.0 flow,
you instead specify the user using the sub claim of the
JWT.

For example, the following HTTP request makes a delegated call using OAuth
1.0:

You can simplify your implementation of the OAuth 2.0 flow by using the
Google API client library for your language.
If you use one of the older Google Data
API client libraries to call GData APIs, you can use the newer Google API
client library to perform the OAuth 2.0 flow, and then call the GData API with
the OAuth 2.0 token. The following examples in Python show the same GData
request authorized using the two-legged OAuth 1.0 flow and the two-legged OAuth 2.0
flow:

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

Important: OAuth 1.0 is
deprecated, and registration of new OAuth 1.0 clients is closed. The information below
is provided only for reference.

Google's OAuth 1.0 endpoints are 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

Important: OAuth 1.0 is
deprecated, and registration of new OAuth 1.0 clients is closed. The information below
is provided only for reference.

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

(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

(required) 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".

OAuth 1.0 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.

OAuth 1.0 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.

OAuthAuthorizeToken

Important: OAuth 1.0 is
deprecated, and registration of new OAuth 1.0 clients is closed. The information below
is provided only for reference.

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.

OAuth 1.0 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

OAuth 1.0 request authorization response

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

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.

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.

If the user grants access, the referenced request token is authorized.

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.

OAuth 1.0 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.

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

OAuthGetAccessToken

Important: OAuth 1.0 is
deprecated, and registration of new OAuth 1.0 clients is closed. The information below
is provided only for reference.

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

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

OAuth 1.0 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.

OAuth 1.0 sample response

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

oauth_token=ab3cd9j4ks73hf7g&oauth_token_secret=ZXhhbXBsZS5jb20

Signing OAuth 1.0 requests (deprecated)

Important: OAuth 1.0 is
deprecated, and registration of new OAuth 1.0 clients is closed. The information below
is provided only for reference.

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.

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.

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.

OAuth 1.0 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.

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 (deprecated)

Important: OAuth 1.0 is
deprecated, and registration of new OAuth 1.0 clients is closed. The information below
is provided only for reference.

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 1.0 requests (deprecated)

Important: OAuth 1.0 is
deprecated, and registration of new OAuth 1.0 clients is closed. The information below
is provided only for reference.