> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pendpost.com/llms.txt
> Use this file to discover all available pages before exploring further.

# YouTube

> Set up YouTube uploads with an OAuth client and a durable refresh token.

The YouTube lane uploads videos and uses native scheduling via `publishAt` where applicable. It publishes only once a YouTube credential is present in your `.env`; until then the lane is live-but-unauthenticated and waits for you to connect it (set `PENDPOST_MODE=mock` to exercise it through the mock driver).

You own your YouTube account and are responsible for YouTube's terms of service. pendpost drafts and schedules, but a human approves before anything goes live.

> [!NOTE]
>
> **Verification and private uploads.** Until your Google Cloud project passes the YouTube API compliance audit, YouTube may force every upload to private regardless of the privacy you request. Verify the project (and pass the audit) to publish publicly; an unverified project keeps its uploads private no matter what pendpost sends.

## Setup ceremony

First create an OAuth client in the Google Cloud console. Then run the interactive auth ceremony, which exchanges the OAuth flow for a durable refresh token and writes it to your `.env`:

```bash theme={null}
node scripts/yt-social.mjs auth
```

## Environment variables

| Variable | Purpose |
| - | - |
| `YT_CLIENT_ID` | Your OAuth client id. |
| `YT_CLIENT_SECRET` | Your OAuth client secret. |
| `YT_REFRESH_TOKEN` | A durable refresh token from the auth ceremony. |
| `YT_REDIRECT_URI` | The OAuth redirect URI (for example `http://localhost:8088/callback`). |

## The refresh token

The auth ceremony mints a durable `YT_REFRESH_TOKEN`. pendpost uses it to obtain fresh access tokens for uploads without re-running the OAuth flow each time, so the lane keeps working unattended.

> [!NOTE]
>
> A lane publishes only once its credential is present. If the YouTube variables are blank, the YouTube lane is live-but-unauthenticated and waits for you to connect it. Set `PENDPOST_MODE=mock` to exercise it through the mock driver.

## Validate the lane

A present credential is not the same as a working one. After setup, validate the YouTube lane in the **Setup** tab, or run a live probe with the `health_recheck` tool, to confirm the credential is live and not just configured. The lane is ready when it reports live.

> [!NOTE]
>
> **Over MCP.** Setup and rotation are an interactive human ceremony; secrets are never written through MCP. An agent can still check status (`account_status`), run a live liveness probe (`health_recheck`), and read non-secret config (`config_get`) over MCP without touching credentials.

## Common failures

| Symptom | Cause | Fix |
| - | - | - |
| Every upload lands as private no matter the privacy you set. | The Google Cloud project has not passed the YouTube API compliance audit. | Verify the project and pass the audit. Until then YouTube forces uploads to private, which is expected, not a pendpost bug. |
| Uploads fail with a 403 `quotaExceeded`. | The daily API quota is exhausted. Uploads are quota-heavy, so a few large videos can exhaust the default allowance. | Wait for the quota to reset, or request a higher quota for the project in the Google Cloud console. |
| Auth fails with `invalid_grant`. | The refresh token was revoked, or the OAuth client secret was rotated. | Re-run `node scripts/yt-social.mjs auth` to mint a fresh `YT_REFRESH_TOKEN`. |
| The callback never completes during setup. | `YT_REDIRECT_URI` does not match a redirect URI registered on the OAuth client. | Register the exact redirect URI (for example `http://localhost:8088/callback`) on the OAuth client, then re-run the auth ceremony. |

## Honest scheduling

For YouTube, pendpost uses native scheduling through `publishAt` and is honest about which thumbnail mechanics actually apply. See [Honest native scheduling](https://docs.pendpost.com/introduction.md#the-five-differentiators) for the broader posture.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.