4

PO Token Guide

coletdjnz edited this page 2025-08-03 10:53:31 +12:00

Table of Contents

• YouTube PO Token Guide
• Introduction
• Cases where a PO Token is required
• Current PO Token enforcement
• PO Token Provider Plugins
• Featured Plugins
• Guide: Providing a PO Token manually (for use with mweb client)
• PO Token for GVS
• PO Token for Player or Subs
• Other PO Token related tools
• Technical details
• PO Tokens for GVS
• PO Tokens for Player and Subs

Go to YouTube Extractor Wiki

YouTube PO Token Guide

Tip

TL;DR recommended setup: Either use a PO Token Provider plugin, or manual extraction, to provide the mweb client with a PO Token for GVS requests.

See the notice in the YouTube Extractor Wiki for more information on the current state of downloading videos from YouTube.

• YouTube PO Token Guide
  • Introduction
  • Cases where a PO Token is required
    • Current PO Token enforcement
  • PO Token Provider Plugins
    • Featured Plugins
  • Guide: Providing a PO Token manually (for use with mweb client)
    • PO Token for GVS
      • No account
      • With an account
    • PO Token for Player or Subs
  • Other PO Token related tools
  • Technical details
    • PO Tokens for GVS
    • PO Tokens for Player and Subs

Introduction

Proof of Origin (PO) Token is a parameter that YouTube requires to be sent with requests from some clients. Without it, requests for the affected clients' format URLs may return HTTP Error 403, or result in your account or IP address being blocked.

A PO Token is generated by an attestation provider on Web, Android and iOS platforms to attest the requests are coming from a genuine client.

For yt-dlp, you can provide PO Token(s) using the po_token extractor argument, or you can install a plugin that hooks into the YouTube extractor to handle fetching a PO Token.

For more technical details on these tokens, refer to the technical details section.

Cases where a PO Token is required

There are currently three cases yt-dlp may require PO Tokens for video downloads, depending on the client used:

• GVS: Google Video Server requests (video streaming - https, dash, hls, etc.)
• Player: Innertube player requests (fetch video format URLs)
• Subs: Subtitle requests

The PO Tokens may be generated differently for each of these cases, depending on the client.

Current PO Token enforcement

YouTube is at present rolling out changes to enforce PO Tokens for video playback. Currently, only GVS and Subs require PO Tokens for some clients.

Client	PO Token Required For	Notes
web	Subs (rolling out), GVS	Only SABR formats available
web_safari	Subs (rolling out), GVS*	Same as web. *Provides HLS (m3u8) formats which do not require PO Token for GVS at this time.
mweb	GVS
tv	Not required	All formats may have DRM if you request too much
tv_simply	Not required	Account cookies not supported
tv_embedded	Not required	Requires account cookies
web_embedded	Not required	Only embeddable videos available
web_music	GVS
web_creator	GVS	Requires account cookies
android	GVS or Player	Account cookies not supported
android_vr	Not required	YouTube Kids videos are not available
ios	GVS or Player (rolling out)	Account cookies not supported

For all clients:

• GVS PO Token is not required for YouTube Premium subscribers
• HLS live streams do not require a PO Token (excluding ios client)

You can select what client to use with the player_client extractor argument.

PO Token Provider Plugins

Tip

Recommended

Manually fetching PO Tokens can be a tedious process. As an alternative, you can install a PO Token Provider plugin to handle fetching PO Tokens automatically.

Featured Plugins

• bgutil-ytdlp-pot-provider by Brainicism
  • A PO Token Provider which uses BgUtils to generate PO Tokens. Not affiliated with yt-dlp.

Check out the yt-dlp-pot-provider GitHub topic for more PO Token Provider plugins.

For developers, refer to the PO Token Provider developer documentation

Guide: Providing a PO Token manually (for use with mweb client)

This section provides a basic guide on extracting PO Token(s) manually from YouTube in a web browser for use with the mweb client, and manually passing it to yt-dlp via the po_token extractor argument. The same PO Token extraction method may work with other web browser-based clients too.

Tip

When supplying multiple PO Tokens, use the same extractor args option and comma-separate the PO Token configurations. For example: --extractor-args "youtube:po_token=mweb.gvs+GVS_PO_TOKEN_VALUE_HERE,mweb.player+PLAYER_PO_TOKEN_VALUE_HERE"

PO Token for GVS

The PO Token used for web GVS requests is tied to your YouTube session, so you will need to provide cookies.

1. Open YouTube Music in a browser.
2. Open the developer console (F12), then go to the "Network" tab (click the >> button if you don't see it)
3. Filter requests by v1/player
4. Play a video - a player request should appear in the network tab
5. From the most recent player request, extract the PO Token from serviceIntegrityDimensions.poToken field in the JSON request body
6. Pass the PO Token for GVS to yt-dlp using --extractor-args "youtube:player-client=default,mweb;po_token=mweb.gvs+PO_TOKEN_VALUE_HERE" with cookies (--cookies COOKIES_FILE or --cookies-from-browser)

If using an account, refer to this guide on exporting account cookies

(Not recommended) If not using an account, you may also provide visitor data instead of cookies. Refer to Passing Visitor Data without cookies.

PO Token for Player or Subs

The PO Token for web/mweb Player or Subs requests is tied to the Video ID. This means you must generate a new PO Token for each video.

1. Open YouTube Web in a browser.
2. Open the developer console (F12), then go to the "Network" tab and filter by v1/player
3. Navigate to the video you want to download (e.g. using search - do not go to the video url directly as the page will refresh)
4. In the request payload JSON, find the PO Token at serviceIntegrityDimensions.poToken and save that value
5. Export cookies from the browser

For Subs PO Token:

• Pass the PO Token for Subs to yt-dlp using --extractor-args "youtube:po_token=web.subs+PO_TOKEN_VALUE_HERE"

For Player PO Token:

Note

If you are using the web client and have not disabled the webpage request, providing this PO Token is not necessary at this time.

• Pass the PO Token for Player to yt-dlp using --extractor-args "youtube:player-client=default,mweb;po_token=mweb.player+PO_TOKEN_VALUE_HERE"

Other PO Token related tools

• BgUtils by LuanRT
  • Utility to generate PoTokens and run BotGuard attestation challenges.
• YouTube Trusted Session Generator by Invidious
  • A generator for getting a session that passes all the checks from YouTube side

Technical details

PO Tokens are still an active area of research, and at the same time YouTube is continuously updating the implementation and enforcement. The following information is based on the current understanding of PO Tokens, and is subject to change.

A PO Token is generated by either BotGuard (Web), DroidGuard (Android), iOSGuard (iOS). A PO Token from one platform cannot be used on another (i.e., Web PO Token cannot be used on Android or iOS).

If you are interested, we recommend checking out the BgUtils project which does a deeper dive into the BotGuard attestation process.

PO Tokens for GVS

GVS uses a PO token bound to the user session.

For Web session tokens:

• When logged out, are bound to a Visitor ID. This Visitor ID is found in the VISITOR_INFO1_LIVE cookie, in the visitorData value which is sent with Innertube API requests, or with ytcfg.get('VISITOR_DATA') in the browser console.
• When logged in, are bound to the account Session ID (first part of the Data Sync ID). This can be found at responseContext.mainAppWebResponseContext.dataSyncId in Innertube responses, or with ytcfg.get('DATASYNC_ID') in the browser console.

If a video download fails with an HTTP 403 midway through, then the client likely requires a PO Token for GVS.

These PO Tokens are only valid for a limited time (usually at least 12 hours), so it will need to be refreshed periodically. However, some reports suggest that the token may be valid for many days.

PO Tokens for Player and Subs

Web Tokens for player (and subtitles) requests are bound to the video ID the associated /player request is for. YouTube has only recently started generating these for some clients (e.g. web).

As of writing, some clients, such as web_music use a session-bound PO Token for player requests. This is likely to change.

For Android (and presumably iOS), the Player PO Token is bound to the user session, similar to GVS tokens. If a Player PO token is provided, the GVS PO token is not required.