Implement authorization

Your application must have authorization credentials to call the YouTube Data API. The API supports two types of credentials:

  • OAuth 2.0: Your application must use the OAuth 2.0 protocol to authorize requests that insert, update, or delete resources, as well as requests that retrieve private user data (such as calling channels.list with mine=true, which retrieves details about the authenticated user's YouTube channel). OAuth 2.0 lets users share specific data with your application while keeping their usernames, passwords, and other account information private.
  • API keys: A request that doesn't provide an OAuth 2.0 token must send an API key. Use an API key for requests that only retrieve public data, such as public video metadata or search results. The key identifies your project and provides API access, quota, and reports.

The OAuth 2.0 authorization process follows these steps:

  • Initiate authorization: When a user attempts to use a feature in your application that accesses private account data, your application directs the user to Google's authorization server.
  • Request scopes: The authorization request specifies the scopes of access that your application requests for the user's account. Scopes define the resources and operations that your application can retrieve, insert, update, or delete on behalf of the authenticated user.
  • Obtain tokens: If the user consents to grant access, Google returns a token or authorization code to your application. Depending on your application type, your application validates the token or exchanges the authorization code for an access token and a refresh token.
  • Call the API: Your application includes the access token in API requests using the Authorization: Bearer <ACCESS_TOKEN> HTTP header (or the access_token query parameter), or by configuring one of the Google API client libraries.

Project setup

Before your application can call the YouTube Data API, complete the following setup steps in the Google Cloud console:

  • Create a project and enable the API: Create or select a project in the Google Cloud console, open the API Library, and enable the YouTube Data API v3.
  • Create an OAuth 2.0 client ID (for private user data): An OAuth 2.0 client ID is a unique identifier that identifies your application to Google's OAuth 2.0 authorization server so your application can request user consent and obtain access and refresh tokens. Open the Credentials page, select Create credentials > OAuth client ID, and choose the application type that matches your platform, such as a web application, client-side JavaScript application, desktop or mobile application, or TV and limited-input device.
  • Create an API key (for public data): If your application makes unauthenticated requests that only retrieve public data, open the Credentials page and select Create credentials > API key. Restrict the key before using it in production by selecting Restrict key and applying application or API restrictions. For more details, see the best practices for securely using API keys.

Access and refresh tokens

OAuth 2.0 uses short-lived access tokens and long-lived refresh tokens:

  • Access tokens: Authorize API requests on the user's behalf. Include the access token in the Authorization: Bearer <ACCESS_TOKEN> HTTP header (or the access_token query parameter), or pass your credentials to a Google API client library. Access tokens have a limited lifetime and expire periodically.
  • Refresh tokens: Let your application obtain a new access token when an existing access token expires, without prompting the user to grant permission again. Server-side web applications obtain refresh tokens by requesting offline access (access_type=offline) during the authorization request. Installed applications and limited-input devices receive refresh tokens automatically when exchanging an authorization code or device code for an access token.

To refresh an access token, send an HTTPS POST request to Google's token endpoint (https://oauth2.googleapis.com/token) that includes your client_id, client_secret (when applicable for your client type), refresh_token, and grant_type=refresh_token.

Google limits the number of refresh tokens issued per client-user combination and per user across all clients. Save refresh tokens in secure, long-term storage and continue to use them as long as they remain valid. If your application requests too many refresh tokens, it can reach these limits, causing older refresh tokens to stop working. For more information, see Refresh token expiration.

Users can revoke access to an application at any time from their Google Account permissions page. Your application can also programmatically revoke an access token or refresh token by sending a POST request to https://oauth2.googleapis.com/revoke?token=<REFRESH_TOKEN>.

API scopes

When directing a user to Google's authorization server, specify one or more of the following OAuth 2.0 scopes to define the level of access your application requests. Request the most narrow scope that supports your application's functionality.

Scope Description
https://www.googleapis.com/auth/youtube Manage your YouTube account.
https://www.googleapis.com/auth/youtube.channel-memberships.creator See a list of your active channel members, their membership level, and when they became a member.
https://www.googleapis.com/auth/youtube.force-ssl See, edit, and permanently delete your YouTube videos, ratings, comments, and captions.
https://www.googleapis.com/auth/youtube.readonly View your YouTube account.
https://www.googleapis.com/auth/youtube.upload Manage your YouTube videos.
https://www.googleapis.com/auth/youtubepartner View and manage your assets and associated content on YouTube.
https://www.googleapis.com/auth/youtubepartner-channel-audit View private information of your YouTube channel relevant during the audit process with a YouTube partner.

OAuth 2.0 flows

Google APIs support several OAuth 2.0 flows for different application architectures. For step-by-step protocol instructions and code samples, see the following Google Identity guides:

For general OAuth 2.0 protocol documentation, see Using OAuth 2.0 to Access Google APIs.