OAuth 2.0 Flow: 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.

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

Embed your client_id and client_secret in your application

You need to obtain authorization credentials in the Google API Console. After setting up your credentials, get the client ID and client secret that were created for your project and embed them into your application. Both values are displayed in the Google API Console.

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:

Parameters

client_id Required. The OAuth 2.0 client ID for your application. You can find this value in the Google API Console.

scope

Required. A space-delimited list of scopes that identify the resources that your application could access on the user's behalf.

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.

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

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.

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 pairs
`client_id`	The OAuth 2.0 client ID for your application. This value is displayed in the API Console.
`client_secret`	The client secret associated with your client ID. This value is displayed in the API 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"
}
```

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.
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.)
User consent decision

After the user logs in, Google's authorization server displays 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.
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.
- 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 the refresh token to obtain a new access token if the one that you have expires.

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:

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

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

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.