RoamTale — YouTube API Services Implementation Document

English implementation document for the YouTube API Services compliance review / quota increase request. This page satisfies the "implementation document" option of the review request (screencast (or) implementation document (or) demo video).

Application: RoamTale · Production URL: https://app.roamtale.io
OAuth redirect URI: https://app.roamtale.io/auth/youtube
Privacy Policy: /Privacy · Terms: /Terms
Scopes: youtube.readonly (read own channel stats & comments) · youtube.force-ssl (upload own videos & reply to comments on own videos)

What the app is: RoamTale is a multi-tenant SaaS application for travel and lifestyle content creators. Each creator signs up for their own isolated account ("tenant") and connects their own YouTube channel via Google OAuth. Every API call is performed exclusively on the authenticated user's own channel, at the user's explicit request. RoamTale never reads from or writes to any other user's channel, and never sells or shares user data. Each tenant's data is stored in a separate, isolated data area.

1. User login & OAuth process

Standard Google OAuth 2.0 Authorization Code flow with offline access (refresh tokens). Implementation: YouTubeOAuthService.cs; callback endpoint /auth/youtube; UI entry point: Personas → <persona> → Profile & Platforms → YouTube → "Connect with YouTube".

The creator clicks "Connect with YouTube". The app builds the authorization URL https://accounts.google.com/o/oauth2/v2/auth with client_id, redirect_uri=https://app.roamtale.io/auth/youtube, response_type=code, scope=youtube.readonly youtube.force-ssl, access_type=offline, prompt=consent and a random state.
Google shows the consent screen listing both scopes; the user authorizes.
Google redirects to /auth/youtube?code=…&state=…; the app validates state and exchanges the code at https://oauth2.googleapis.com/token (grant_type=authorization_code) for an access_token + refresh_token.
The channel id is fetched via GET /youtube/v3/channels?part=id&mine=true; tokens + channel id are stored per persona, inside that creator's isolated tenant area.
Token refresh: access tokens (~1 h) auto-refresh via the refresh token (grant_type=refresh_token) ~20 min before expiry, so automation never uses an expired token.
Disconnect / revocation: "Disconnect" calls https://oauth2.googleapis.com/revoke and deletes the stored tokens for that tenant.

2. Uploading videos to the YouTube channel (youtube.force-ssl)

Implementation: YouTubePublisher.cs. The creator uploads one of their own generated videos to their own channel via videos.insert (multipart):

POST https://www.googleapis.com/upload/youtube/v3/videos?uploadType=multipart&part=snippet,status
Authorization: Bearer <access_token>
Content-Type: multipart/related
  part 1 (application/json):
    { "snippet": { "title": …, "description": …, "categoryId": "22" },
      "status":  { "privacyStatus": "public", "selfDeclaredMadeForKids": false } }
  part 2 (video/mp4): <the creator's own video bytes>

Short uploads append #Shorts so YouTube classifies the vertical (<60 s) clip as a Short. The API returns the new video id; the app builds the watch/Shorts URL and shows a success message. Quota/error responses (e.g. quotaExceeded) are surfaced to the creator verbatim (the quota ceiling is the reason for this quota-increase request).

3. Channel analytics displayed in the dashboard (youtube.readonly)

Implementation: Connectors.cs → YouTubeConnector.GetStatsAsync, pulled periodically by MetricsPullService and shown on the Dashboard (/). Read-only, own channel only:

GET /youtube/v3/channels?part=statistics,contentDetails&id={channelId} → subscriberCount, videoCount, uploads playlist.
GET /youtube/v3/videos?part=statistics&id={videoIds} → sums per-video viewCount + likeCount (accurate for Shorts, where the channel aggregate lags).

The dashboard displays the connected channel's subscriber count, total views, total likes and video count — only on that creator's own private dashboard. No data from any other channel is read or displayed.

4. Replying to comments (read: youtube.readonly · write: youtube.force-ssl)

Implementation: Connectors.cs (YouTubeConnector) + SocialAutomationService.cs; UI: the Inbox page.

Read comments on the creator's own channel: GET /youtube/v3/commentThreads?allThreadsRelatedToChannelId={channelId}&part=snippet.
Reply: POST /youtube/v3/comments?part=snippet with { "snippet": { "parentId": <comment id>, "textOriginal": <reply text> } } — posted as the channel owner, only on the creator's own videos, at the creator's request (optionally assisted by an AI-drafted suggestion that the creator sends).

The app never reads or writes comments on videos that do not belong to the connected creator's own channel.

5. Data handling, storage & security

Per-channel scope: every call targets the authenticated creator's own channel id only — no cross-channel access between users.
Tenant isolation: each creator's data (including their YouTube tokens) lives in a separate, isolated per-tenant data area; one tenant can never access another tenant's tokens or data.
Token storage: access/refresh tokens are stored per persona within the creator's tenant area ({TENANT_DATA_ROOT}/config/personas.json); never sent to any third party.
Refresh & revoke: tokens auto-refresh server-side; the creator can revoke at any time via "Disconnect" (calls Google's revoke endpoint and deletes the local tokens).
Transport: the app runs behind HTTPS (https://app.roamtale.io); the OAuth redirect URI and the OAuth consent screen domain match this production domain.
Minimal data: only the creator's own channel/video statistics and the creator's own comments are read; nothing is shared or published outside the creator's own channel.

6. Where each item lives

Requirement	Scope	Code	UI
OAuth login	both	YouTubeOAuthService.cs, /auth/youtube	Personas → YouTube → "Connect"
Upload videos	force-ssl	YouTubePublisher.cs (videos.insert)	Persona → "Upload as Short / video"
Channel analytics	readonly	Connectors.cs YouTubeConnector (channels.list + videos.list)	Dashboard /
Reply to comments	readonly + force-ssl	Connectors.cs (commentThreads.list, comments.insert)	Inbox
Disconnect / revoke	—	YouTubeOAuthService.DisconnectAsync (oauth2/revoke)	YouTube → "Disconnect"

A complementary English screencast/demo video of the live app can additionally be provided on request. Contact: admin@roamtale.io.