YouTube

Implementing OAuth 2.0 Authentication

The YouTube Analytics API supports the OAuth 2.0 protocol for authorizing access to private user data. The list below explains some core OAuth 2.0 concepts:

  • When a user first attempts to use functionality in your application that requires the user to be logged in to a Google Account or YouTube account, your application initiates the OAuth 2.0 authentication process.

  • Your application directs the user to Google's authorization server. The link to that page specifies the scope of access that your application is requesting for the user's account. The scope specifies the resources that your application can retrieve, insert, update, or delete when acting as the authenticated user.

  • If the user consents to authorize your application to access those resources, Google will return a token to your application. Depending on your application's type, it will either validate the token or exchange it for a different type of token.

    For example, a server-side web application would exchange the returned token for an access token and a refresh token. The access token would let the application authenticate requests on the user's behalf, and the refresh token would let the application retrieve a new access token when the original access token expires.

This section of the API documentation covers the following topics:

  • The OAuth 2.0 flows section explains the flows for obtaining OAuth 2.0 access tokens for either server-side web applications, client-side web applications, installed applications, or devices. The Google Accounts Authentication and Authorization documentation also provides complete details for implementing OAuth 2.0 in different types of applications.

  • The Calling the YouTube Analytics API section explains how to use the OAuth 2.0 tokens that your application obtains to make authenticated API requests on a user's behalf.

  • The Client libraries section describes client library support for OAuth 2.0.

Important: You need to register your application with Google to be able to use OAuth 2.0 authentication.

OAuth 2.0 flows

Google supports several OAuth 2.0 use cases:

  • The server-side flow supports web applications that can securely store persistent information.
  • The client-side flow supports JavaScript applications running in a browser.
  • The installed application flow supports applications installed on a device, such as a phone or computer.
  • The device flow supports devices with limited input capabilities, such as game consoles and video cameras.
Server-side web applications

This flow is designed for web applications with servers that can store information and maintain state. While this section walks through the steps your code would go through to use OAuth 2.0 in a server-side web application, you could also use one of several client libraries in your OAuth 2.0 implementation.

The following steps explain the server-side flow:

  1. Obtain 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 will refuse HTTP connections.

    When a user first tries to perform an action that requires API authentication, direct the user to Google's authorization server at https://accounts.google.com/o/oauth2/auth. It supports the following URL parameters:

    Parameter Description
    client_id Required. The OAuth 2.0 client ID for your application.
    redirect_uri Required. A registered redirect_uri for that client ID.
    response_type Required. Set this 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.
    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 refresh access tokens when the user is not present. (This is the method of refreshing access tokens described later in this document.)
    state Optional. Any string that your application would use to maintain state between the request and redirect response. Your application will receive the same value that it sends for this parameter. For example, you could use this parameter to redirect the user to a particular resource in your application.

    The sample URL below shows a redirect to Google's authorization server for an application requesting permission to submit YouTube Analytics API requests on the user's behalf:

    https://accounts.google.com/o/oauth2/auth?
      client_id=1084945748469-eg34imk572gdhu83gj5p0an9fut6urp5.apps.googleusercontent.com&
      redirect_uri=http://localhost/oauth2callback&
      scope=https://www.googleapis.com/auth/yt-analytics.readonly&
      response_type=code&
      access_type=offline
    
  2. User decides whether to grant access to your application

    Google's authorization server will display the name of your application and the Google services that it is requesting permission to access on the user's behalf. 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 step 1. If you also place a file on your server at http://localhost/oauth2callback, you will also be able to see how the user's response appears in the redirect URI. (See step 3 for more details.)

  3. Google redirects user to your application

    After the user consents or refuses to grant access to your application, Google will redirect 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 will have included the access_denied error message in the hash fragment of the redirect_uri:

      http://localhost/oauth2callback#error=access_denied
  4. 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
    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.
    client_secret The client secret associated with your client ID. This value is displayed in the Google APIs 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
    
  5. 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"
    }
    

    Important: Your application should store both values.

Client-side web applications

This flow is designed for JavaScript-based web applications that cannot maintain state over time.

The following steps explain the client-side flow:

  1. Obtain 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 will refuse HTTP connections.

    When a user first tries to perform an action that requires API authentication, direct the user to Google's authorization server at https://accounts.google.com/o/oauth2/auth. It supports the following URL parameters:

    Parameter Description
    client_id Required. The OAuth 2.0 client ID for your application.
    redirect_uri Required. A registered redirect_uri for that client ID.
    response_type Required. Set this parameter's value to token.
    scope Required. A space-delimited list of scopes that identify the resources that your application could access on the user's behalf.
    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.
    state Optional. A string used to maintain state between the request and redirect. This value will be appended to your redirect_uri after the user consents to or denies your application's access request.

    The sample URL below shows a redirect to Google's authorization server for an application requesting permission to submit YouTube Analytics API requests on the user's behalf:

    https://accounts.google.com/o/oauth2/auth?
      client_id=1084945748469-eg34imk572gdhu83gj5p0an9fut6urp5.apps.googleusercontent.com&
      redirect_uri=http://localhost/oauth2callback&
      scope=https://www.googleapis.com/auth/yt-analytics.readonly&
      response_type=token
    
  2. User decides whether to grant access to your application

    Google's authorization server will display the name of your application and the Google services that it is requesting permission to access on the user's behalf. 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 step 1. If you also place a file on your server at http://localhost/oauth2callback, you will also be able to see how the user's response appears in the redirect URI. (See step 3 for more details.)

  3. Google redirects user to your application

    After the user consents or refuses to grant access to your application, Google will redirect 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 short-lived access token in the hash fragment of the redirect URI. The response will also include the expires_in and token_type parameters. These parameters describe the lifetime of the token in seconds and the kind of token that is being returned, respectively. Finally, the response will include the state parameter if a state parameter was included in the original request to the authorization server.

      http://localhost/oauth2callback#access_token=1/QbIbRMWW&token_type=Bearer&expires_in=3600

      Note: Your application should also allow other fields to be returned in the response. The list provided above identifies the minimum set of fields that will be appended to the redirect_uri.

      JavaScript code running on your page can capture the access token from the window.location.hash value and either store the token in a cookie or POST it to a server.

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

      http://localhost/oauth2callback#error=access_denied
  4. Validate the user's token

    Assuming the user has granted access to your application, you need to explicitly validate the token returned in the redirect_uri. You validate the token by specifying the token as the value of the access_token parameter in a web service request to https://www.googleapis.com/oauth2/v1/tokeninfo. That URL accepts an access token and returns information about that token, including the application that the token was issued to, the user associated with the token, the scopes that the user granted access to, and the remaining life of the token.

    The sample URL below demonstrates where you would send a token validation request:

    https://www.googleapis.com/oauth2/v1/tokeninfo?access_token=1/fFBGRNJru1FQd44AzqT3Zg
  5. Process the token validation response

    In response to a token validation request, the Google authorization server will return either a JSON object that describes the token or an error message.

    • If the token is still valid, the JSON object will include the following values:

      Field Description
      audience The application that is the intended user of the access token.

      Important: Before using the token, you need to verify that this field's value exactly matches your client_id in the Google APIs console. This verification ensures that your application will not be vulnerable to the confused deputy problem.
      expires_in The number of seconds left before the token will become invalid.
      scope A space-delimited list of scopes that the user granted access to. The list should match the scopes you specified in your authorization request in step 1.
      userid This value lets you correlate profile information from multiple Google APIs. It is only present in the response if you included the https://www.googleapis.com/auth/userinfo.profile scope in your request in step 1. The field value is an immutable identifier for the logged-in user that can be used to create and manage user sessions in your application.

      A sample response is shown below:

      {
        "audience":"8819981768.apps.googleusercontent.com",
        "user_id":"123456789",
        "scope":"https://www.googleapis.com/auth/yt-analytics.readonly",
        "expires_in":436
      }
      
    • If the token has expired, been tampered with, or had its permissions revoked, Google's authorization server will return an error message in the JSON object. The error surfaces as a 400 error, and a JSON body in the format shown below:

      {"error":"invalid_token"}

      By design, no additional information is given as to the reason for the failure.

Installed applications

This flow is designed for applications that are installed on a device, such as a mobile phone or computer. These applications could access the YouTube Analytics API 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 YouTube Analytics 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.

The following steps explain this flow:

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

  2. Obtain 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 will refuse HTTP connections.

    When a user first tries to perform an action that requires API authentication, direct the user to Google's authorization server at https://accounts.google.com/o/oauth2/auth. It supports the following URL parameters:

    Parameter Description
    client_id Required. The OAuth 2.0 client ID for your application.
    redirect_uri

    Required. A registered redirect_uri for that client ID. For installed applications, you can choose between an http://localhost:port or urn:ietf:wg:oauth:2.0:oob as described below:

    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 Google APIs 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 will then need to extract 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. Set this 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.
    state Optional. Any string that your application would use to maintain state between the request and redirect response. Your application will receive the same value that it sends for this parameter. For example, you could use this parameter to redirect the user to a particular resource in your application.

    The sample URL below shows a redirect to Google's authorization server for an application requesting permission to submit YouTube Analytics API requests on the user's behalf:

    https://accounts.google.com/o/oauth2/auth?
      client_id=1084945748469-eg34imk572gdhu83gj5p0an9fut6urp5.apps.googleusercontent.com&
      redirect_uri=http://localhost/oauth2callback&
      scope=https://www.googleapis.com/auth/yt-analytics.readonly&
      response_type=code&
      access_type=offline
    
  3. User decides whether to grant access to your application

    Google's authorization server will display the name of your application and the Google services that it is requesting permission to access on the user's behalf. 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 step 2. If you also place a file on your server at http://localhost/oauth2callback, you will also be able to see how the user's response appears in the redirect URI. (See step 4 for more details.)

  4. Google redirects user to your application

    After the user consents or refuses to grant access to your application, Google will either redirect the user to the redirect_uri that you specified in step 2 or return a page to the user's browser.

    • If you set the redirect_uri to http://localhost (or some path on the local web server), then one of the following two scenarios will apply:

      • 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 5.

        http://localhost/oauth2callback?code=4/ux5gNj-_mIu4DOD_gNZdjX9EtOFf
      • If the user refused to grant access to your application, Google will have included the access_denied error message in the hash fragment of the redirect_uri:

        http://localhost/oauth2callback#error=access_denied
    • If you set the redirect_uri to urn:ietf:wg:oauth:2.0:oob, Google's authorization server will return a page to the browser like the one shown below. Your application can then extract 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 a code= or error= 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 the code 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

  5. 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 to https://accounts.google.com/o/oauth2/token that includes the following key-value pairs in the request body:

    Key Value
    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.
    client_secret The client secret associated with your client ID. This value is displayed in the Google APIs 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
    
  6. 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"
    }
    

    Important:Your application should store both values.

Devices

This flow is designed for applications that run on devices with limited input capabilities, such as game consoles or video cameras. In this flow, the user interacts with an application on the device to obtain a URL and a device code. The user then switches to another device, such as a computer or smartphone, that has richer input capabilities to authorize the device code.

The following steps explain this flow:

  1. Embed your client_id and client_secret in your application

    You need to register your application with Google and embed the client_id and client_secret created during the registration process into your application.

  2. Request a device code

    Your device sends a POST request to Google's authorization server at https://accounts.google.com/o/oauth2/device/code. The request specifies the following parameters:

    Parameter Description
    client_id Required. The OAuth 2.0 client ID for your application.
    scope Required. A space-delimited list of scopes that identify the resources that your application could access on the user's behalf.

    The following sample request shows how to retrieve a device code:

    POST /o/oauth2/device/code HTTP/1.1
    Host: accounts.google.com
    Content-Type: application/x-www-form-urlencoded
    
    client_id=1084945748469-eg34imk572gdhu83gj5p0an9fut6urp5.apps.googleusercontent.com&
    scope=https://www.googleapis.com/auth/yt-analytics.readonly
    
  3. Handle the response

    Google will respond to your request by returning a JSON object to your device. A sample response is shown below:

    {
      "device_code" : "4/L9fTtLrhY96442SEuf1Rl3KLFg3y",
      "user_code" : "a9xfwk9c",
      "verification_url" : "http://www.google.com/device",
      "expires_in" : "1800"
      "interval" : 5,
    }
    

    The application on your device should display the user_code and verification_url to the user. It should store the device_code, expires_in, and interval values for use in step 4.

  4. Begin polling Google's authorization server

    Your application can begin polling Google's authorization server using the device_code returned in the JSON response in step 3. To do so, your application sends a POST request to https://accounts.google.com/o/oauth2/token that specifies the following key-value pairs:

    Key Value
    client_id The OAuth 2.0 client ID for your application.
    client_secret The client secret associated with your client ID. This value is displayed in the Google APIs console.
    code The device code obtained in step 3.
    grant_type Set this value to http://oauth.net/grant_type/device/1.0.

    A sample polling request is shown below. The interval returned in the JSON response in step 3 specifies the minimum amount of time, in seconds, that your application should wait between polling requests.

    POST /o/oauth2/token HTTP/1.1
    Host: accounts.google.com
    Content-Type: application/x-www-form-urlencoded
    
    client_id=1084945748469-eg34imk572gdhu83gj5p0an9fut6urp5.apps.googleusercontent.com&
    client_secret=hDBmMRhz7eJRsM9Z2q1oFBSem&
    code=4/YMSlR3fSCC1NtUh073DuZKTJJ3ss&
    grant_type=http://oauth.net/grant_type/device/1.0
    

    Until the user completes steps 5 through 7, your application will receive one of the following responses to each polling request:

    • The following response indicates that the user has not yet completed the steps to grant API access to the device:

      {
        "error" : "authorization_pending"
      }
      
    • The following response indicates that your application is sending polling requests too frequently:

      {
        "error" : "slow_down"
      }
      
  5. User enters user_code in separate browser

    The user launches a browser on another device, such as a computer or mobile phone, and navigates to the verification_url. That URL will display a page where the user can enter the user_code obtained in step 3.

    Note: The user_code is case-sensitive, so the user will need to enter it exactly as it appears in the response.

  6. User logs in to Google Account that will be used on your device

    After entering the user_code, the user will be asked to log in to the Google Account that will be used to authenticate YouTube Analytics API requests from your device. (If the user is already logged in, she will proceed directly to the next step.)

  7. User decides whether to grant access to your application

    After the user logs in, Google's authorization server will display a page that shows the name of your application and the Google services that it is requesting permission to access on the user's behalf. The user can then consent or refuse to grant access to your application.

  8. Process response from polling server to obtain tokens

    If the user grants access to your application, the next polling request that your device sends will return a JSON object that contains an access token and a refresh token.

    {
      "access_token":"1/fFAGRNJru1FTz70BzhT3Zg",
      "expires_in":3920,
      "token_type":"Bearer",
      "refresh_token":"1/6BMfW9j53gdGImsixUH6kU5RsR4zwI9lUVX-tqf8JXQ"
    }
    

    Important: Your application should store both values.

Calling the YouTube Analytics API

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 access_token query parameter:

    www.googleapis.com/youtube/analytics/v1/reports?access_token=ACCESS_TOKEN

    You can test this using cURL with the following command:

    curl www.googleapis.com/youtube/analytics/v1/reports?access_token=YOUR_ACCESS_TOKEN&part=id&mine=true
    
  2. Specify the access token as the value of the Authorization: Bearer HTTP request header:

    GET /youtube/analytics/v1/reports 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" www.googleapis.com/youtube/analytics/v1/reports?part=id&mine=true
    

The API will return an HTTP 401 response code (Unauthorized) if you submit a request to access a protected resource with an expired access token. The following section explains how to refresh an access token.

Refreshing an access token

If your application obtains a refresh token during the authorization process, then you will need to periodically use that token to obtain a new, valid access token. Server-side web applications, installed applications, and devices all obtain refresh tokens.

At any time, your application can send 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 should also set 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 will return a JSON object that contains a new access token:

{
  "access_token":"1/fFAGRNJru1FTz70BzhT3Zg",
  "expires_in":3920,
  "token_type":"Bearer"
}

Client libraries

You can use the client libraries listed below to implement OAuth 2.0 in your application:

You can also follow the instructions in the Calling the YouTube Analytics API section to modify your code to properly set the OAuth 2.0 token values.

Authentication required

You need to be signed in with Google+ to do that.

Signing you in...

Google Developers needs your permission to do that.