OAuth 2.0 Flow: Server-side web apps

This OAuth 2.0 flow is designed for web applications with servers that can store confidential information and maintain state. These applications can access the YouTube Data API while the user is actually using the application or after the user has left the application.

This scenario begins when a user tries to perform an action that requires authorization. The application redirects the user to a Google URL that contains query parameters that specify the type of API access the application requires.

Google handles the user authentication and consent, then returns an authorization code. The application uses that code, along with its client_id and client_secret, to obtain an access token, which can then be used to authorize API requests on the user's behalf. During that step, the application can also request a refresh token, which enables the application to obtain a new access token when the previously obtained access token expires.

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:

Obtaining OAuth 2.0 access tokens

This flow has the following steps:

  1. Request an access token

    Note: Requests to Google's authorization server must use https instead of http 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. Register valid redirect URIs for your application in the API Console.
    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 a channel resource.
    approval_prompt Optional. This parameter indicates whether the user should be prompted to grant account access to your application each time she tries to complete a particular action. The default value is auto, which indicates that a user would only need to grant access the first time she tried to access a protected resource.

    Set the parameter value to force to direct the user to a consent page even if she has already granted access to your application for a particular set of scopes.
    access_type Recommended. This parameter indicates whether your application can refresh access tokens when the user is not present at the browser. Valid parameter values are online and offline. Set this parameter value to offline to allow the application to use refresh tokens when the user is not present. (This is the method of refreshing access tokens described later in this document.)
    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 the redirect_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.
    login_hint Optional. If your application knows which user is trying to authenticate, it can use this parameter to provide a hint to Google's Authentication Server. The server uses the hint to simplify the login flow by either prefilling the email field in the sign-in form or selecting the appropriate multi-login session.

    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

  2. Handle response from Google

    After the user consents or refuses to grant access to your application, Google redirects the user to the redirect_uri that you specified in step 1.

    • If the user granted access to your application, Google will have appended a code parameter to the redirect_uri. This value is a temporary authorization code that you can exchange for an access token as discussed in step 4.

      http://localhost/oauth2callback?code=4/ux5gNj-_mIu4DOD_gNZdjX9EtOFf

    • If the user refused to grant access to your application, Google includes the access_denied error message in the hash fragment of the redirect_uri:

      http://localhost/oauth2callback#error=access_denied

  3. Exchange authorization code for refresh and access tokens

    Assuming the user has granted access to your application, exchange the authorization code obtained in step 3 for a refresh token and access token. To do so, send a POST request to https://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 3.
    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

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

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. The API supports two ways to specify an access token:

  1. Specify the access token as the value of the Authorization: Bearer HTTP request header. This is the recommended approach.

    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

  2. Specify the access token as the value of the access_token query parameter:

    https://www.googleapis.com/youtube/v3/channels?part=id&mine=true&access_token=ACCESS_TOKEN

    You can test this using cURL with the following command:

    curl https://www.googleapis.com/youtube/v3/channels?part=id&mine=true&access_token=ACCESS_TOKEN

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:

    1. 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.
    2. Follow the link to the Security settings page.
    3. 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 is 400 and the response also contains an error code.

Client libraries

Sign-in with Google

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.

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.