> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/darkzOGx/youtube-automation-agent/llms.txt
> Use this file to discover all available pages before exploring further.

# YouTube Setup

> Complete guide to configuring YouTube API, authentication, and channel settings

This guide walks you through the complete YouTube API setup process, from creating credentials to authenticating your channel.

## Prerequisites

Before starting, ensure you have:

* A YouTube channel
* A Google account with access to the channel
* [Google Cloud Console](https://console.cloud.google.com/) access

<Warning>
  You must be the owner or have manager permissions on the YouTube channel to authorize the application.
</Warning>

***

## Step 1: Create Google Cloud Project

<Steps>
  <Step title="Open Google Cloud Console">
    Navigate to [Google Cloud Console](https://console.cloud.google.com/)
  </Step>

  <Step title="Create New Project">
    1. Click the project dropdown at the top
    2. Click **"New Project"**
    3. Enter project details:
       * **Project name**: `YouTube Automation Agent`
       * **Organization**: Leave default or select your organization
    4. Click **"Create"**
  </Step>

  <Step title="Wait for Project Creation">
    The project will be created in a few seconds. You'll see a notification when it's ready.
  </Step>
</Steps>

***

## Step 2: Enable YouTube APIs

<Steps>
  <Step title="Navigate to APIs & Services">
    1. Select your project from the dropdown
    2. Click on the hamburger menu (☰)
    3. Go to **"APIs & Services"** → **"Library"**
  </Step>

  <Step title="Enable YouTube Data API v3">
    1. Search for **"YouTube Data API v3"**
    2. Click on it
    3. Click **"Enable"**

    <Note>
      This API is required for uploading videos, managing playlists, and accessing channel information.
    </Note>
  </Step>

  <Step title="Enable YouTube Analytics API">
    1. Search for **"YouTube Analytics API"**
    2. Click on it
    3. Click **"Enable"**

    <Note>
      This API provides access to video performance metrics and analytics data.
    </Note>
  </Step>
</Steps>

***

## Step 3: Configure OAuth Consent Screen

Before creating credentials, you must configure the OAuth consent screen:

<Steps>
  <Step title="Navigate to OAuth Consent Screen">
    Go to **"APIs & Services"** → **"OAuth consent screen"**
  </Step>

  <Step title="Select User Type">
    Choose **"External"** and click **"Create"**

    <Accordion title="Internal vs External">
      * **Internal**: Only for Google Workspace organizations
      * **External**: For personal accounts and general use (choose this)
    </Accordion>
  </Step>

  <Step title="Fill App Information">
    **App name**: Your channel name or "YouTube Automation Agent"

    **User support email**: Your email address

    **App logo**: (Optional) Upload your channel logo

    **Application home page**: (Optional) Your website or channel URL

    **Developer contact information**: Your email address
  </Step>

  <Step title="Configure Scopes">
    1. Click **"Add or Remove Scopes"**
    2. Add these YouTube scopes:

    ```
    https://www.googleapis.com/auth/youtube.upload
    https://www.googleapis.com/auth/youtube
    https://www.googleapis.com/auth/youtube.readonly
    https://www.googleapis.com/auth/yt-analytics.readonly
    ```

    <Accordion title="What each scope does">
      * `youtube.upload` - Upload videos
      * `youtube` - Manage videos and channel
      * `youtube.readonly` - Read channel information
      * `yt-analytics.readonly` - Access analytics data
    </Accordion>

    3. Click **"Update"**
  </Step>

  <Step title="Add Test Users (Optional)">
    While in development/testing mode, add your Google account email as a test user.

    <Note>
      In testing mode, only test users can authorize the app. For production use, you'll need to submit for verification.
    </Note>
  </Step>

  <Step title="Review and Save">
    Review your settings and click **"Save and Continue"** through all screens.
  </Step>
</Steps>

***

## Step 4: Create OAuth 2.0 Credentials

<Steps>
  <Step title="Navigate to Credentials">
    Go to **"APIs & Services"** → **"Credentials"**
  </Step>

  <Step title="Create OAuth Client ID">
    1. Click **"+ Create Credentials"**
    2. Select **"OAuth client ID"**
  </Step>

  <Step title="Configure Application Type">
    **Application type**: Select **"Web application"**

    **Name**: `YouTube Automation OAuth Client`
  </Step>

  <Step title="Add Authorized Redirect URIs">
    Under **"Authorized redirect URIs"**, add:

    ```
    http://localhost:8080/oauth2callback
    ```

    <Warning>
      The redirect URI must match exactly what's configured in your application. Port 8080 is the default.
    </Warning>

    If you're running on a different port, update accordingly:

    ```
    http://localhost:YOUR_PORT/oauth2callback
    ```
  </Step>

  <Step title="Create and Download">
    1. Click **"Create"**
    2. A dialog will show your Client ID and Client Secret
    3. Click **"Download JSON"** or copy the credentials
  </Step>
</Steps>

***

## Step 5: Configure Application

Now add the credentials to your application:

<Tabs>
  <Tab title="Using credentials.json">
    Create or edit `config/credentials.json`:

    ```json config/credentials.json theme={null}
    {
      "youtube": {
        "client_id": "123456789-abcdefg.apps.googleusercontent.com",
        "client_secret": "GOCSPX-abc123def456",
        "redirect_uris": [
          "http://localhost:8080/oauth2callback"
        ]
      },
      "channel": {
        "channelName": "Your Channel Name",
        "channelDescription": "Your channel description",
        "defaultCategory": "24",
        "defaultPrivacy": "public",
        "websiteUrl": "https://yourwebsite.com",
        "businessEmail": "your@email.com"
      }
    }
    ```
  </Tab>

  <Tab title="Using Setup Wizard">
    Run the interactive setup:

    ```bash theme={null}
    npm run credentials:setup
    ```

    The wizard will prompt you for:

    1. YouTube API Client ID
    2. YouTube API Client Secret
    3. Redirect URI (default: `http://localhost:8080/oauth2callback`)
    4. Channel configuration details
  </Tab>

  <Tab title="Using Downloaded JSON">
    If you downloaded the JSON from Google Cloud:

    1. Rename it to `google-credentials.json`
    2. Place it in the `config/` directory
    3. The application will automatically parse it
  </Tab>
</Tabs>

***

## Step 6: Authenticate Your Channel

Now authenticate the application with your YouTube channel:

<Steps>
  <Step title="Run Authentication">
    ```bash theme={null}
    node authenticate.js
    ```

    Or use the setup command:

    ```bash theme={null}
    npm run setup
    ```
  </Step>

  <Step title="Authorization URL">
    The console will display an authorization URL:

    ```
    🔗 Please visit this URL to authorize the application:
    https://accounts.google.com/o/oauth2/v2/auth?access_type=offline&scope=...
    ```

    Copy and open this URL in your browser.
  </Step>

  <Step title="Grant Permissions">
    1. Sign in with your Google account (if not already signed in)
    2. Select the YouTube channel to authorize
    3. Review the requested permissions:
       * Upload videos
       * Manage your YouTube account
       * View YouTube Analytics reports
    4. Click **"Allow"**

    <Warning>
      If you see a "This app isn't verified" warning, click **"Advanced"** → **"Go to \[App Name] (unsafe)"**. This is normal for apps in testing mode.
    </Warning>
  </Step>

  <Step title="Copy Authorization Code">
    After granting permissions, you'll see an authorization code or be redirected to `localhost:8080`.

    If shown a code:

    1. Copy the code
    2. Paste it into the terminal when prompted

    If redirected:

    1. The application will automatically capture the code
    2. Authentication will complete automatically
  </Step>

  <Step title="Verify Success">
    You should see:

    ```
    ✅ YouTube authentication completed!
    ✅ Tokens saved to config/tokens.json
    ```
  </Step>
</Steps>

***

## Step 7: Verify Configuration

Test that everything is working:

<Steps>
  <Step title="Run Test Script">
    ```bash theme={null}
    npm test
    ```

    This will verify:

    * YouTube API connection
    * Channel access
    * Upload permissions
    * Analytics access
  </Step>

  <Step title="Check Channel Info">
    The test should output your channel information:

    ```
    ✅ Connected to channel: Your Channel Name
    📊 Subscriber count: 1,234
    🎬 Total videos: 56
    👁️  Total views: 123,456
    ```
  </Step>
</Steps>

***

## Channel Configuration

Configure channel-specific settings in `config/credentials.json`:

```json theme={null}
{
  "channel": {
    "channelName": "Your Channel Name",
    "channelDescription": "Description of your channel",
    "defaultCategory": "24",
    "defaultPrivacy": "public",
    "websiteUrl": "https://yoursite.com",
    "businessEmail": "business@email.com"
  },
  "content": {
    "contentTypes": ["tutorial", "explainer", "story"],
    "competitorChannels": [],
    "targetAudience": "Tech enthusiasts aged 18-35",
    "postingFrequency": "daily",
    "preferredPostTime": "14:00"
  }
}
```

### Video Category IDs

<Accordion title="YouTube Category Reference">
  | ID | Category              |
  | -- | --------------------- |
  | 1  | Film & Animation      |
  | 2  | Autos & Vehicles      |
  | 10 | Music                 |
  | 15 | Pets & Animals        |
  | 17 | Sports                |
  | 19 | Travel & Events       |
  | 20 | Gaming                |
  | 22 | People & Blogs        |
  | 23 | Comedy                |
  | 24 | Entertainment         |
  | 25 | News & Politics       |
  | 26 | Howto & Style         |
  | 27 | Education             |
  | 28 | Science & Technology  |
  | 29 | Nonprofits & Activism |
</Accordion>

### Privacy Settings

<Tabs>
  <Tab title="public">
    **Recommended for:** Growth-focused channels

    * Appears in search results
    * Recommended to viewers
    * Counts toward watch time
    * Eligible for monetization
  </Tab>

  <Tab title="unlisted">
    **Recommended for:** Testing, client reviews

    * Only accessible via direct link
    * Not shown in search or recommendations
    * Counts toward watch time
    * Can be monetized
  </Tab>

  <Tab title="private">
    **Recommended for:** Drafts, personal videos

    * Only you can see
    * Share with specific users
    * Not indexed
    * Cannot be monetized
  </Tab>
</Tabs>

***

## Content Strategy Configuration

Configure what types of content to generate:

```json theme={null}
{
  "content": {
    "contentTypes": [
      "tutorial",
      "explainer",
      "list",
      "story",
      "review"
    ],
    "competitorChannels": [
      "UCxxxxxxxxxxxxxx",
      "UCyyyyyyyyyyyyyy"
    ],
    "targetAudience": "Tech enthusiasts interested in AI and automation",
    "postingFrequency": "daily",
    "preferredPostTime": "14:00"
  }
}
```

### Content Types

<CardGroup cols={2}>
  <Card title="Tutorial" icon="graduation-cap">
    Step-by-step instructional videos teaching specific skills or processes.
  </Card>

  <Card title="Explainer" icon="lightbulb">
    Educational content explaining concepts, technologies, or phenomena.
  </Card>

  <Card title="List" icon="list">
    Top 10, best of, or compilation-style videos (e.g., "5 Ways to...").
  </Card>

  <Card title="Story" icon="book">
    Narrative-driven content with storytelling elements.
  </Card>

  <Card title="Review" icon="star">
    Analysis and opinions on products, services, or content.
  </Card>
</CardGroup>

***

## Posting Schedule

Configure automated posting:

```json theme={null}
{
  "content": {
    "postingFrequency": "daily",
    "preferredPostTime": "14:00",
    "timezone": "America/New_York"
  }
}
```

### Frequency Options

| Value          | Description                 |
| -------------- | --------------------------- |
| `daily`        | One video per day           |
| `every-2-days` | Every other day             |
| `3-per-week`   | Three times per week        |
| `weekly`       | Once per week               |
| `custom`       | Define custom cron schedule |

### Best Posting Times

<Accordion title="By Audience Location">
  **US Audience:**

  * 12:00 PM - 4:00 PM EST (lunch/afternoon)
  * 7:00 PM - 10:00 PM EST (evening)

  **European Audience:**

  * 2:00 PM - 4:00 PM CET
  * 8:00 PM - 10:00 PM CET

  **Global Audience:**

  * 1:00 PM - 3:00 PM UTC
</Accordion>

<Note>
  The system will analyze your channel's analytics to recommend optimal posting times after collecting sufficient data.
</Note>

***

## Token Refresh

OAuth tokens expire periodically. The system automatically refreshes them:

```javascript theme={null}
// Automatic refresh logic
if (tokens.expiry_date < Date.now()) {
  const { credentials } = await oauth2Client.refreshAccessToken();
  oauth2Client.setCredentials(credentials);
  await saveTokens(credentials);
}
```

<Warning>
  If you see authentication errors, the refresh token may be invalid. Re-run authentication:

  ```bash theme={null}
  node authenticate.js
  ```
</Warning>

***

## Quota Management

YouTube API has daily quota limits:

* **Default quota**: 10,000 units/day
* **Upload video**: 1,600 units
* **Update video**: 50 units
* **List videos**: 1 unit

### Monitor Usage

Check quota usage in [Google Cloud Console](https://console.cloud.google.com/apis/api/youtube.googleapis.com/quotas):

1. Select your project
2. Navigate to **"APIs & Services"** → **"YouTube Data API v3"**
3. Click **"Quotas"**

### Request Quota Increase

If you need more quota:

1. Go to **"IAM & Admin"** → **"Quotas"**
2. Filter for "YouTube Data API v3"
3. Select the quota to increase
4. Click **"Edit Quotas"**
5. Fill out the request form

<Note>
  Quota increases are usually approved within 24-48 hours for reasonable requests.
</Note>

***

## Troubleshooting

<Accordion title="Error: redirect_uri_mismatch">
  **Solution:**

  1. Check that redirect URI in code matches Google Cloud Console exactly
  2. Ensure there are no trailing slashes or typos
  3. Verify the port number matches

  Update in Google Cloud Console:

  * Go to Credentials → OAuth 2.0 Client IDs
  * Edit your client
  * Update redirect URIs
</Accordion>

<Accordion title="Error: Access Not Configured">
  **Solution:**

  1. Ensure YouTube Data API v3 is enabled in your project
  2. Wait a few minutes after enabling APIs
  3. Clear browser cache and try again
</Accordion>

<Accordion title="Error: Invalid Credentials">
  **Solution:**

  1. Verify client\_id and client\_secret are correct
  2. Check for extra spaces or line breaks when copying
  3. Re-download credentials JSON from Google Cloud Console
</Accordion>

<Accordion title="Token Expired Errors">
  **Solution:**

  Re-authenticate:

  ```bash theme={null}
  rm config/tokens.json
  node authenticate.js
  ```
</Accordion>

<Accordion title="Quota Exceeded">
  **Solution:**

  1. Wait until quota resets (daily at midnight Pacific Time)
  2. Reduce upload frequency
  3. Request quota increase
  4. Use `GLOBAL_RATE_LIMIT_PER_HOUR` to throttle requests
</Accordion>

***

## Security Best Practices

<CardGroup cols={2}>
  <Card title="Protect Credentials" icon="lock">
    * Never commit `credentials.json` or `tokens.json` to git
    * Add to `.gitignore`
    * Use environment variables in production
  </Card>

  <Card title="Rotate Keys" icon="key">
    * Regenerate OAuth credentials every 6 months
    * Delete old unused credentials
    * Use different credentials for dev/prod
  </Card>

  <Card title="Limit Scopes" icon="shield">
    * Only request necessary OAuth scopes
    * Review permissions periodically
    * Revoke unused authorizations
  </Card>

  <Card title="Monitor Access" icon="eye">
    * Check authorized apps in Google Account settings
    * Enable 2FA on Google account
    * Review API access logs
  </Card>
</CardGroup>

***

## Next Steps

Your YouTube configuration is complete! Now you can:

<CardGroup cols={2}>
  <Card title="Start the Agent" icon="play" href="/quickstart">
    Launch the YouTube Automation Agent and start generating content
  </Card>

  <Card title="Configure Agents" icon="robot" href="/features/ai-agents">
    Customize the specialized AI agents for your channel
  </Card>
</CardGroup>