YouTube

Implementing OAuth 2.0 Authentication

The YouTube Data 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 authorization 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 returns a token to your application. Depending on your application's type, it either validates the token or exchanges it for a different type of token.

    For example, a server-side web application exchanges the returned token for an access token and a refresh token. The access token lets the application authorize requests on the user's behalf, and the refresh token lets 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 Data API 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.

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

OAuth 2.0 flows

Google APIs support 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.
  • The service account flow supports server-to-server interactions that do not access user information. However, the YouTube Data API does not support this flow. Since there is no way to link a Service Account to a YouTube account, attempts to authorize requests with this flow will generate a NoLinkedYouTubeAccount error.

Implementing OAuth 2.0

Click the tab below that corresponds to the OAuth 2.0 flow appropriate to your application.

Server-side web applications

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.

This flow has the following steps:

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

    Parameter Description
    client_id Required. The OAuth 2.0 client ID for your application. You can find this value in the APIs Console.
    redirect_uri Required. A registered redirect_uri for your client ID. Register valid redirect URIs for your application in the APIs 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:

    Scope Description
    https://www.googleapis.com/auth/youtube Manage your YouTube account.
    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 YouTube Data 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 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
  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
    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 APIs console.
    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
    
  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"
    }
    

    Important: Your application should store both values in a secure, long-lived location that is accessible between different invocations of your application. The refresh token enables your application to obtain a new access token if the one that you have expires. As such, if your application loses the refresh token, the user will need to repeat the OAuth 2.0 consent flow so that your application can obtain a new refresh token.

Client-side web applications

This OAuth 2.0 flow is designed to enable JavaScript-based web applications to send authorized Google API requests. These applications cannot maintain state over time, meaning that the application accesses the YouTube Data API while the user is present at the application. This flow assumes that the application cannot store confidential information.

This flow has the following steps:

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

    Parameter Description
    client_id Required. The OAuth 2.0 client ID for your application. You can find this value in the APIs Console.
    redirect_uri Required. A registered redirect_uri for your client ID. Register valid redirect URIs for your application in the APIs Console.
    response_type Required. Determines whether the Google OAuth 2.0 endpoint returns an authorization code. JavaScript applications need to set the parameter's value to token. This instructs the Google Authorization Server to return the access token as a name=value pair in the hash (#) fragment of the redirect URI that the server returns.
    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:

    Scope Description
    https://www.googleapis.com/auth/youtube Manage your YouTube account.
    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.
    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 YouTube Data 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=token
    
  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 appends a short-lived access token in the hash fragment of the redirect URI as shown in the sample URI below. The response also includes 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 includes 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 parameters to be included in the response's hash fragment. The paragraph above describes the minimum set of name-value pairs returned in 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
  3. 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. By validating, or verifying, the token, you ensure that your application is not vulnerable to the confused deputy problem.

    To validate the token, send a request to https://www.googleapis.com/oauth2/v1/tokeninfo and set the token as the access_token parameter's value. That URL accepts and returns information about the 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 time before the token expires.

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

    https://www.googleapis.com/oauth2/v1/tokeninfo?access_token=ACCESS_TOKEN
  4. Process the token validation response

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

    • If the token is valid, the JSON object includes the following properties:

      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 is not vulnerable to the confused deputy problem.
      expires_in The number of seconds left before the token becomes invalid.
      scope A space-delimited list of scopes that the user granted access to. The list should match the scopes 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/youtube",
        "expires_in":436
      }
      
    • If the token has expired, been tampered with, or had its permissions revoked, Google's authorization server returns 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.

      Note: In practice, a 400 error typically indicates that the access token request URL was malformed, often due to improper URL escaping.

Installed applications

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 access the YouTube Data 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 Data 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.

This flow has the following steps:

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

    Parameter Description
    client_id Required. The OAuth 2.0 client ID for your application. You can find this value in the APIs Console.
    redirect_uri Required. A registered redirect_uri for your client ID. When you register an installed application, two redirect_uri values are automatically created for you: http://localhost:port and urn: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 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 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:

    Scope Description
    https://www.googleapis.com/auth/youtube Manage your YouTube account.
    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.
    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.

    The sample URL below shows a Google's authorization server URI that requests permission for an application to submit YouTube Data 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
    
  3. 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 to http://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 the redirect_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 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 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 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

  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 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. This value is displayed in the Google APIs console.
    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 in a secure, long-lived location that is accessible between different invocations of your application. The refresh token enables your application to obtain a new access token if the one that you have expires. As such, if your application loses the refresh token, the user will need to repeat the OAuth 2.0 consent flow so that your application can obtain a new refresh token.

Devices

This OAuth 2.0 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.

This flow has the following steps:

  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. Both values are displayed in the Google APIs console.

  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/youtube
    
  3. Handle response from Google

    Google responds 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 receives 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 displays a page where the user can enter the user_code obtained in step 3.

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

  6. User logs in to Google Account

    After entering the user_code, the user is asked to log in to the Google Account that will be used to authorize YouTube Data API requests from your device. (Users who are already logged in proceed directly to the next step.)

  7. Process response from polling server to obtain tokens

    If the user grants access to your application, the next polling request that your device sends returns 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 Data 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 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 the OAuth 2.0 authentication mechanism along with additional access to social features of Google+.

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 Calling the YouTube Data 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.