Click here to see your recently viewed pages and most viewed pages.
Hide

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

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:

  1. Revoke the access token associated with your application for your user account:
    1. Go to Google's Account Permissions page.
    2. Select your application from the list.
    3. Click Revoke access.
  2. Access your application.
    • If the consent screen includes a deprecation notice, you must migrate to OAuth 2.0.
    • If the URL of the consent screen includes the string /oauth1, you must migrate to OAuth 2.0.

Prerequisites for this migration:

  • Your application must have a valid OAuth 1.0 access token (which implies that your application has a valid grant).
  • Your application must have an OAuth 2.0 client ID and client secret. You get these OAuth 2.0 credentials by registering the application as a web app or a native app in the Google Developers Console.

To find your OAuth 2.0 credentials in the Google Developers Console:

  1. Go to the Google Developers Console.
  2. Select a project, or create a new one.
  3. In the sidebar on the left, expand APIs & auth. Next, click APIs. Select the Enabled APIs link in the API section to see a list of all your enabled APIs. Make sure that the Google Sign-In API is on the list of enabled APIs. If you have not enabled it, select the API from the list of APIs, then select the Enable API button for the API.
  4. In the sidebar on the left, select Credentials.

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.

The flow is as follows:

  1. The process is triggered when an OAuth 1.0 consumer (your application) sends a migration request to Google’s OAuth 2.0 token endpoint.
  2. The credentials in the migration request are validated.
  3. An OAuth 2.0 refresh token is issued to your application in the response to your migration request.
  4. Your application uses OAuth 2.0 flows to exchange the refresh token for an OAuth 2.0 access token. (Note that when the refresh token is used, the OAuth 1.0 access token will expire in 1 hour.)

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:

Authorization: OAuth realm="example",
               oauth_consumer_key="9djdj82h48djs9d2",
               oauth_token="kkk9d7dh3k39sjv7",
               oauth_signature_method="HMAC-SHA1",
               oauth_timestamp="137131201",
               oauth_nonce="7d8f3e4a",
               oauth_signature="bYT5CMsGcbgUdFHObYMEfcx6bsw%3D"

All the fields are required except realm. Applications can use any OAuth 1.0 library to generate the header.

There are three required OAuth 2.0 request parameters (grant_type, client_id, and client_secret) and an optional parameter (scope):

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

    Required. This is a fixed value.

  • client_id

    Required. This is the OAuth 2.0 client ID, which you get from the Google Developers Console.

  • client_secret

    Required. This is the OAuth 2.0 client secret, which you get from the Google Developers Console.

  • scope

    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.

POST /oauth2/v3/token HTTP/1.1
Host: www.googleapis.com
Content-Type: application/x-www-form-urlencoded
Content-Length: 88
Authorization: OAuth realm="example",
               oauth_consumer_key="9djdj82h48djs9d2",
               oauth_token="kkk9d7dh3k39sjv7",
               oauth_signature_method="HMAC-SHA1",
               oauth_timestamp="137131201",
               oauth_nonce="7d8f3e4a",
               oauth_signature="bYT5CMsGcbgUdFHObYMEfcx6bsw%3D"
grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Amigration%3Aoauth1&
client_id=8819981768.apps.googleusercontent.com&
client_secret=YOUR_CLIENT_SECRET

A note on the signature: Make sure to follow the OAuth1 signature specification when signing your migration request.

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

An example response is shown below:

{
  "refresh_token" : "1/IJ8bRmYIH4t6iE761H3XW9JwqzsGFCA8wnQ7gck_3NU"
}

Obtaining an OAuth 2.0 access token

Exchange the refresh token for an OAuth 2.0 access token, as described in Using a refresh token.

About refresh tokens:

  • Refresh tokens never expire unless revoked.
  • It is the responsibility of your client software to store the refresh token permanently and securely.

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.

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

    POST /oauth2/v3/token HTTP/1.1
    Host: www.googleapis.com
    Content-Type: application/x-www-form-urlencoded
    Content-Length: 473
    
    oauth_consumer_secret=anonymous&
    oauth_consumer_key=anonymous&
    oauth_token=YOUR_TOKEN_SECRET&
    client_id=8819981768.apps.googleusercontent.com&
    client_secret=YOUR_CLIENT_SECRET&
    scope=https%3A%2F%2Fdocs.google.com%2Ffeeds%2F+https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fgoogletalk+https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fdocs&oauth_token_secret=hrUbfZIRxIgpC_AN-arCYDsJ&
    grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Amigration%3Aoauth1
    

    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