Implement authorization

  • The YouTube Reporting API and YouTube Analytics API utilize OAuth 2.0 for authorizing access to private user data.

  • OAuth 2.0 requires user consent, and the scope requested determines the resources the application can access, with a possible inverse relationship between the number of scopes and the likelihood of consent.

  • Google's OAuth 2.0 supports various flows including server-side web apps, JavaScript web apps, and mobile/desktop apps, but it doesn't support the device flow for YouTube Reporting and Analytics APIs, or the service account flow.

  • Before implementing OAuth 2.0, it's recommended to identify the necessary scopes, with specific scopes for the YouTube Analytics API and YouTube Reporting API being detailed, as well as a document containing a full list of possible scopes for Google APIs.

  • If your application uses scopes that permit access to certain user data, you might need to complete a verification process, especially if you encounter an "unverified app" warning.

Every request to the YouTube Reporting API and YouTube Analytics API must be authorized using the OAuth 2.0 protocol because both APIs access private channel or content owner analytics data. Neither API supports unauthenticated or API key-only requests. The APIs support two OAuth 2.0 account models:

  • User accounts: Authorize requests on behalf of a Google Account that owns a YouTube channel or is linked to a YouTube Content Manager (content owner) account. OAuth 2.0 lets users share specific data with your application while keeping their usernames, passwords, and other account information private. For content-owner requests (requests that set the onBehalfOfContentOwner parameter or set ids=contentOwner==<OWNER_NAME>), users must sign in during OAuth 2.0 consent with the Google Account granted permissions in YouTube Studio Content Manager, not a YouTube channel or Brand Account (which fails content-owner authorization with an HTTP 403 error).
  • Service accounts (content owners only): Authorize automated server-to-server requests on behalf of a YouTube Content Manager account (requests that set onBehalfOfContentOwner in the YouTube Reporting API or on YouTube Analytics API groups and groupItems methods, set ids=contentOwner==<OWNER_NAME> on YouTube Analytics API reports.query requests, or download content-owner reports through media.download). A service account can't authenticate or act as a YouTube channel. To retrieve data for a channel that a content owner manages, send a content-owner request that filters by that channel (such as ids=contentOwner==<OWNER_NAME> with filters=channel==<CHANNEL_ID> on reports.query).

Both APIs support channel and content owner requests:

  • Channel requests: Retrieve reports or manage groups for a YouTube channel. In the YouTube Analytics API, pass ids=channel==MINE (or ids=channel==<CHANNEL_ID>) to reports.query, and omit onBehalfOfContentOwner on groups and groupItems requests (such as passing mine=true to groups.list). In the YouTube Reporting API, omit onBehalfOfContentOwner so the request runs against the authenticated user's channel.
  • Content owner requests: Retrieve reports or manage groups on behalf of a YouTube Content Manager account using an authorized user account or service account. In the YouTube Analytics API, pass ids=contentOwner==<OWNER_NAME> to reports.query or onBehalfOfContentOwner to groups and groupItems methods. In the YouTube Reporting API, set the onBehalfOfContentOwner parameter on reportTypes, jobs, and jobs.reports requests (for media.download, content-owner access is authorized from the report's downloadUrl resource name).

For user-authorized applications, the OAuth 2.0 authorization process follows these steps:

  • Initiate authorization: When a user attempts to use a feature in your application that accesses YouTube Analytics 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 access 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 Reporting API or YouTube Analytics API, create a project in the Google Cloud console, and then create the credential that matches how your application authorizes requests: an OAuth 2.0 client ID for user authorization, or a service account for automated content-owner requests. Most applications need only one of the two.

  • Create a project and enable the APIs: Create or select a project in the Google Cloud console, open the API Library, and enable the YouTube Reporting API and YouTube Analytics API (plus the YouTube Data API v3 if your application also retrieves channel, playlist, or video metadata).
  • Create an OAuth 2.0 client ID (for user authorization): 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, or desktop or mobile application.
  • Create a service account (for content owners): If your application uses automated server-to-server authentication on behalf of a YouTube Content Manager account, open the Credentials page, select Create credentials > Service account, and generate a private key. Invite the service account email address under Settings > Permissions in YouTube Studio Content Manager to authorize content-owner requests. Don't configure Google Workspace domain-wide delegation or include a sub claim in service account token requests. For the service account protocol, see Using OAuth 2.0 for Server to Server Applications.

Access and refresh tokens

OAuth 2.0 uses short-lived access tokens and long-lived refresh tokens. For the full protocol, see Using OAuth 2.0 to Access Google APIs.

  • Access tokens: Authorize API requests on the account'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, and can use incremental authorization (include_granted_scopes=true) to request additional scopes later (such as requesting monetary report access only when a user uses a revenue feature). Installed applications receive refresh tokens automatically when exchanging an authorization code for an access token. Service accounts don't use refresh tokens; instead, your application signs a JSON Web Token (JWT) with the service account's private key and exchanges it for a new access token.

To refresh a user 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.

YouTube Reporting API (v1)

Scope Description
https://www.googleapis.com/auth/yt-analytics.readonly View YouTube Analytics reports for your YouTube content. Grants access to list non-monetary report types, create and manage non-monetary reporting jobs, and list or download non-monetary user activity reports (such as views and ratings).
https://www.googleapis.com/auth/yt-analytics-monetary.readonly View monetary and non-monetary YouTube Analytics reports for your YouTube content. Required to list monetary report types, create or manage monetary reporting jobs, and list or download monetary and revenue reports. For content-owner requests, the user or service account must also have a role under Settings > Permissions in YouTube Studio Content Manager that includes permission to view revenue data. Without it, access to monetary data is denied.

YouTube Analytics API (v2)

Scope Description
https://www.googleapis.com/auth/yt-analytics.readonly View YouTube Analytics reports for your YouTube content. Grants reports.query access to non-monetary user activity metrics (such as views and ratings) and read-only access to list YouTube Analytics groups (groups.list). When paired with youtube.readonly, also grants read-only access to list group items (groupItems.list).
https://www.googleapis.com/auth/yt-analytics-monetary.readonly View monetary and non-monetary YouTube Analytics reports for your YouTube content. Required for reports.query requests that retrieve monetary or revenue metrics. For content-owner requests, the user or service account must also have a role under Settings > Permissions in YouTube Studio Content Manager that includes permission to view revenue data. Without it, access to monetary data is denied. Doesn't grant standalone access to groups or groupItems methods.
https://www.googleapis.com/auth/youtube Manage your YouTube account. Grants reports.query access to non-monetary metrics, and channel owners use this scope to view, create, update, and delete YouTube Analytics groups and group items.
https://www.googleapis.com/auth/youtube.readonly View your YouTube account. Grants reports.query access to non-monetary metrics, and must be paired with yt-analytics.readonly to list group items (groupItems.list). Doesn't grant standalone access to groups or groupItems methods.
https://www.googleapis.com/auth/youtubepartner View and manage your assets and associated content on YouTube. Grants reports.query access to non-monetary metrics, and content owners use this scope to view, create, update, and delete YouTube Analytics groups and group items.

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.