This OAuth 2.0 flow is designed for applications that are installed on a device, such as a mobile phone or computer. These applications can send API requests while the user is interacting with the application or when the application is running in the background for an extended period of time without direct user interaction.
This flow assumes that the application cannot securely store tokens that would enable a user to interact with the API. It also requires that the application has access to the system browser or has the ability to embed a browser control. If the application does not meet either of these conditions, refer to the OAuth 2.0 instructions for devices by clicking the Devices tab above.
Important: You need to obtain authorization credentials in the Google API Console to be able to use OAuth 2.0 authorization.
This document contains the following sections:
-
The Obtaining OAuth 2.0 access tokens section explains how to obtain OAuth 2.0 access tokens for installed applications. The Google Accounts Authentication and Authorization documentation also provides complete details for implementing OAuth 2.0 in different types of applications.
-
The Making an authorized API request section explains how to use the OAuth 2.0 tokens that your application obtains to make authorized API requests on a user's behalf.
-
The Client libraries section describes client library support for OAuth 2.0.
Obtaining OAuth 2.0 access tokens
This flow has the following steps:
-
Register your application as an installed application
When registering your application, make sure that you specify that it is an installed application. This results in a different default value for the
redirect_uri
parameter. -
Request an access token
Note: Requests to Google's authorization server must use
https
instead ofhttp
because the server is only accessible over SSL (HTTPs) and refuses HTTP connections.When a user first tries to perform an action that requires API authentication, you need to direct the user to Google's authorization server at
https://accounts.google.com/o/oauth2/auth
. The table below identifies the request parameters that you need to (or can) include in the URL. Note that the request URI that you construct must contain properly URL-escaped parameter values.Parameters client_id
Required. The OAuth 2.0 client ID for your application. You can find this value in the API Console. redirect_uri
Required. A registered redirect_uri
for your client ID. When you register an installed application, tworedirect_uri
values are automatically created for you:http://localhost:port
andurn:ietf:wg:oauth:2.0:oob
. The descriptions below can help you choose the appropriate value for your application.http://localhost:port
- This value indicates that Google's authorization server should return the authorization code as a query string parameter to the client device's web server. You may specify a port number without changing the configuration in the API Console.
To receive the authorization code on this URL, your application must be listening on the local web server. If your platform supports it, this is the recommended mechanism for obtaining the authorization code. However, note that not all platforms support this approach and that even if a platform does support it, other software (e.g. Windows firewall) may prevent delivery of the message. urn:ietf:wg:oauth:2.0:oob
- This value indicates that Google's authorization server should return the authorization code in the browser's title bar. This option is useful if the client cannot listen on an HTTP port without significant modifications to the client. Windows applications possess this characteristic.
If your application uses this value, it needs to determine when the browser has loaded a response from the authorization server. It then extracts the authorization code from the title of the page served in the browser. See step 4 for specific instructions for parsing the token from the page title.
Your application should also close the browser window if you want to prevent the user from seeing the page with the authorization code. The mechanism for closing that window varies from platform to platform.
response_type
Required. Determines whether the Google OAuth 2.0 endpoint returns an authorization code. Set the parameter's value to code
.scope
Required. A space-delimited list of scopes that identify the resources that your application could access on the user's behalf. These values determine which permissions are listed on the consent page that Google displays to the user.
The YouTube Data API supports the following scopes:
Scopes https://www.googleapis.com/auth/youtube.force-ssl Manage your YouTube account. This scope requires communication with the API server to happen over an SSL connection. https://www.googleapis.com/auth/youtube Manage your YouTube account. This scope is functionally identical to the youtube.force-ssl
scope listed above because the YouTube API server is only available via an HTTPS endpoint. As a result, even though this scope does not require an SSL connection, there is actually no other way to make an API request.https://www.googleapis.com/auth/youtube.readonly View your YouTube account. https://www.googleapis.com/auth/youtube.upload Upload YouTube videos and manage your YouTube videos. https://www.googleapis.com/auth/youtubepartner-channel-audit Retrieve the auditDetails
part in achannel
resource.state
Optional. A string that your application uses to maintain state between the request and redirect response. The exact value that you send is returned as a name=value
pair in the hash (#
) fragment of theredirect_uri
after the user consents to or denies your application's access request. You could use this parameter for several purposes, such as directing the user to the correct resource in your application, sending nonces, and mitigating cross-site request forgery.The sample URL below shows a Google's authorization server URI that requests permission for an application to submit API requests on the user's behalf. Note that parameter values must be properly URL-escaped.
https://accounts.google.com/o/oauth2/auth? client_id=1084945748469-eg34imk572gdhu83gj5p0an9fut6urp5.apps.googleusercontent.com& redirect_uri=http%3A%2F%2Flocalhost%2Foauth2callback& scope=https://www.googleapis.com/auth/youtube& response_type=code& access_type=offline
-
User consent decision
In this step, the user decides whether to grant your application the ability to make API requests that are authorized as the user. Google's authorization server displays the name of your application and the Google API services that it is requesting permission to access with the user's authorization credentials. The user can then consent or refuse to grant access to your application.
You can test this flow by clicking on the sample URL in the previous step. You can also see how the user's response appears in the redirect URI by placing a file on your server at
http://localhost/oauth2callback
. (See the next step for more details.) -
Handle response from Google
After the user consents or refuses to grant access to your application, Google either redirects the user to the
redirect_uri
that you specified in step 2 or returns a page to the user's browser.-
If you set the
redirect_uri
tohttp://localhost
(or some path on the local web server), then one of the following two scenarios apply:-
If the user granted access to your application, Google appends a
code
parameter to theredirect_uri
as shown in the sample URL below. Its value specifies a single-use authorization code that you exchange for an access token as discussed in step 5.http://localhost/oauth2callback?code=SINGLE_USE_CODE
-
If the user refused to grant access to your application, Google includes the
access_denied
error message in the hash fragment of theredirect_uri
:http://localhost/oauth2callback#error=access_denied
-
-
If you set the
redirect_uri
tourn:ietf:wg:oauth:2.0:oob
, Google's authorization server returns a page to the browser like the one shown below. Your application then extracts the authorization code from the page title.To extract the token, your application should assume that everything that follows the last space character in the page title is a parameter string in the format
x=a&y=b
. Your code should parse the parameters from that substring, looking for acode=
orerror=
assignment to indicate that the page contains the final title string and the sign-in flow is complete. If the page title assigns a value to thecode
parameter, then that value is the token. However, your application should not make assumptions about the token length or the number of parameters in the parameter string.For example, the screenshot below shows a page with the following attributes:
- Page title:
Success code=4/v6xr77ewYqhvHSyW6UJ1w7jKwAzu
- Parameter string:
code=4/v6xr77ewYqhvHSyW6UJ1w7jKwAzu
- Authorization token:
4/v6xr77ewYqhvHSyW6UJ1w7jKwAzu
- Page title:
-
-
Exchange authorization code for refresh and access tokens
Assuming the user has granted access to your application, exchange the authorization code obtained in step 4 for a refresh token and access token. To do so, send a
POST
request tohttps://accounts.google.com/o/oauth2/token
that includes the following key-value pairs in the request body:Key-value pairs code
The authorization code that Google returned to your redirect_uri
in step 4.client_id
The OAuth 2.0 client ID for your application. This value is displayed in the Google Developers console. client_secret
The client secret associated with your client ID. This value is displayed in the Google Developers console. redirect_uri
A registered redirect_uri
for your client ID.grant_type
Set this value to authorization_code
.A sample request is displayed below:
POST /o/oauth2/token HTTP/1.1 Host: accounts.google.com Content-Type: application/x-www-form-urlencoded code=4/ux5gNj-_mIu4DOD_gNZdjX9EtOFf& client_id=1084945748469-eg34imk572gdhu83gj5p0an9fut6urp5.apps.googleusercontent.com& client_secret=hDBmMRhz7eJRsM9Z2q1oFBSe& redirect_uri=http://localhost/oauth2callback& grant_type=authorization_code
-
Process response and store tokens
Google will respond to your
POST
request by returning a JSON object that contains a short-lived access token and a refresh token.{ "access_token" : "ya29.AHES6ZTtm7SuokEB-RGtbBty9IIlNiP9-eNMMQKtXdMP3sfjL1Fc", "token_type" : "Bearer", "expires_in" : 3600, "refresh_token" : "1/HKSmLFXzqP0leUihZp2xUt3-5wkU7Gmu2Os_eBnzw74" }
-
The Making an authorized API request section explains how to submit an authorized request using the access token.
-
The Refreshing an access token section explains how to use a refresh token to obtain a new access token.
-
Making an authorized API request
After obtaining an access token for a user, your application can use that token to submit
authorized API requests on that user's behalf. Specify the access token as the value of the
Authorization: Bearer
HTTP request header
GET /youtube/v3/channels?part=id&mine=true HTTP/1.1 Host: www.googleapis.com Authorization: Bearer ACCESS_TOKEN ...
You can test this using cURL with the following command:
curl -H "Authorization: Bearer ACCESS_TOKEN" https://www.googleapis.com/youtube/v3/channels?part=id&mine=true
The API returns an HTTP 401 response code (Unauthorized) if you submit a request to access a protected resource with an access token that is expired, bogus, improperly scoped, or invalid for some other reason.
If the API returns an HTTP 403 response code, then your application may not be registered. Many APIs set a query-volume limit of 0
for unregistered applications and return a 403 response code when the query-volume limit is exceeded.
The following section explains how to refresh an access token.
Refreshing an access token
Access tokens periodically expire and, when that happens, need to be refreshed. When an access token expires or at any other time, your application may be able to use a refresh token to obtain a new, valid access token. Server-side web applications, installed applications, and devices all obtain refresh tokens during the authorization process.
To refresh an access token, your application sends a POST
request to Google's authorization server that specifies your client ID, your client secret, and the refresh token for the user. The request also sets the grant_type
parameter value to refresh_token
. The following example demonstrates this request:
POST /o/oauth2/token HTTP/1.1 Host: accounts.google.com Content-Type: application/x-www-form-urlencoded client_id=21302922996.apps.googleusercontent.com& client_secret=XTHhXh1SlUNgvyWGwDk1EjXB& refresh_token=1/6BMfW9j53gdGImsixUH6kU5RsR4zwI9lUVX-tqf8JXQ& grant_type=refresh_token
The authorization server returns a JSON object that contains a new access token:
{ "access_token":"1/fFAGRNJru1FTz70BzhT3Zg", "expires_in":3920, "token_type":"Bearer" }
Note that there are limits on the number of refresh tokens that will be issued; one limit per client/user combination, and another per user across all clients. You should save refresh tokens in long-term storage and continue to use them as long as they remain valid. If your application requests too many refresh tokens, it may run into these limits, in which case older refresh tokens will stop working.
Revoking a Token
There are two ways to revoke an access token:
-
A user can revoke access given to an application by visiting the following URL and explicitly revoking access:
https://accounts.google.com/b/0/IssuedAuthSubTokens
The following steps explain how to reach this page:
- Click on the user's picture in the Google sandbar and then click the Account link or navigate in some other way to the Account Overview page for the user's Google Account.
- Follow the link to the Security settings page.
- Click the button to manage access to connected applications and websites that can access and use details from the user's Google Account.
-
An application can programmatically revoke its own access. This type of revocation is important in instances where a user unsubscribes or removes an application, in which an API request to remove the permissions granted to the application should be a part of the removal process.
To programmatically revoke a token, your application sends a request to
https://accounts.google.com/o/oauth2/revoke
and includes the token as a parameter:curl https://accounts.google.com/o/oauth2/revoke?token={token}
The specified token can be an access token or a refresh token. If the token is an access token and it has a corresponding refresh token, the refresh token is also revoked.
If the revocation succeeds, the response's status code is
200
. If an error occurs, the response's status code is400
and the response also contains an error code.
Client libraries
Note: If you are planning to provide a sign-in with Google feature, we recommend using Google Sign-in, which provides an OAuth 2.0 authentication mechanism.
You can use the client libraries listed below to implement OAuth 2.0 in your application. We recommend using a client library rather than writing your own code. Using these standard client libraries is important for the safety and security of your users and your application.
- Google APIs Client Library for Java
- Google APIs Client Library for JavaScript
- Google APIs Client Library for Python
- Google APIs Client Library for .NET
- Google APIs Client Library for Ruby
- Google APIs Client Library for PHP
- OAuth 2.0 Library for Google Web Toolkit
- Google Toolbox for Mac OAuth 2.0 Controllers
You can also follow the instructions in the Making an authorized API request section to modify your code to properly set the OAuth 2.0 token values.