Getting your platform API keys

Phoenix Clips publishes from your own accounts through your own API credentials — nothing goes through Phoenix’s servers, and Phoenix never sees your tokens. The price of that is a one-time setup walk through three developer consoles. This page is the walk.

Where the values go depends on where your instance runs:

• Local install: the panel’s Settings → This install tab — each section below names the exact fields. Credentials land in the Windows credential store, encrypted under your account.
• Self-hosted cloud: the same names as environment variables on your host (FB_APP_ID, YT_CLIENT_ID, …).

Treat every token like a password. Access tokens, refresh tokens, app secrets and client secrets give full access to your accounts. If one ends up on a screenshot, in a public chat, in git or in a support ticket — consider it leaked and issue a new one.

Facebook and Instagram (Meta)

One (free) Meta app covers both platforms. The chain looks like this: your Facebook user → a Facebook Page → the Instagram professional account linked to that Page → your Meta app → tokens → publishing and insights.

Before you start

• You manage a Facebook Page — a Page, not just a personal profile.
• Your Instagram account is switched to Professional (Business or Creator).
• That Instagram account is linked to the Facebook Page.
• You sign in to Meta for Developers as the Facebook user who manages that Page.

1. Link Instagram to the Facebook Page

Being signed in to instagram.com is not the link — the Page itself has to know the account:

1. On Facebook, switch from your profile to the Page.
2. Open Settings & privacy → Settings → Linked accounts (or the Instagram entry).
3. Connect account, sign in to the right Instagram account, confirm.

If OAuth later says “You don’t have any Instagram accounts” — the account isn’t Professional, or the link above wasn’t made from the Page.

2. Create the Meta app

1. Meta for Developers → My Apps → Create App.
2. Any clear name; check the contact email; Next.
3. On Use cases pick Content management → Manage everything on your Page → Next.
4. On Business, “I don’t want to connect a business portfolio yet” is fine.
5. Finish. Your App ID and App secret are under App settings → Basic — these are the first two fields in the panel’s Facebook & Instagram section.

3. Add the Facebook permissions

Use cases → Manage everything on your Page → Customize → Permissions and features. The service uses exactly these:

Permission	Why Phoenix Clips needs it
pages_show_list	find the Page and mint its token
pages_read_engagement	read the Page’s own posts
pages_manage_posts	publish the clip
read_insights	views and reach
pages_manage_engagement	reel insights, and posting the first comment as the Page

If Meta insists on business_management for its current flow, add it; skip anything else it merely offers.

4. Add Instagram to the same app

1. Add the use case Manage messaging & content on Instagram.
2. In Instagram API, choose API setup with Facebook login — not “with Instagram login”, which is a different flow with different tokens.
3. Under Manage content on Instagram → Go to permissions and features, enable:

Permission	Why
instagram_basic	see the professional account
instagram_content_publishing	publish Reels (older docs call it instagram_content_publish — take whichever your dashboard shows)
instagram_manage_insights	plays and reach
instagram_manage_comments	the automatic first comment
instagram_manage_contents	delete a Reel when you pull the clip back — without it a published Reel can never be removed from here, and the clip can never be re-published

5. Generate the token and connect

1. Put App ID and App secret into the panel first: Settings → This install → Facebook & Instagram, save.
2. Open Tools → Graph API Explorer, select your app, keep the host on graph.facebook.com (switching to .instagram.com is a different API, not “an Instagram token”).
3. Add the permissions from both tables and press Generate Access Token. In the OAuth window grant access to the right Page and its Instagram account — selecting only those is enough.
4. Copy the token into Settings → Connections → Facebook & Instagram and press Connect.

The panel exchanges that short-lived token server-side for a 60-day user token and a permanent Page token; nothing short-lived is stored. The Connections tab shows both expiry dates, and the same screen lists any permission the token turned out to be missing.

If something fails

Symptom	Check
You don’t have any Instagram accounts	Instagram is Professional? Linked to the Page itself, not just Accounts Center? OAuth done as the user who manages the Page?
Invalid Scopes on a permission	It has to be enabled in Use cases → Permissions and features first, then requested in the Explorer.
Instagram visible in the browser but not in OAuth	A browser session is not a Page link — redo step 1.

YouTube

Two ways to connect, same result — videos land on your own channel either way:

1. Authorize with Google — one click in the panel, nothing to set up. Pending Google’s review of our shared app; the button in Settings → Connections lights up the moment it’s approved.
2. Your own OAuth client — the route below. ~20 minutes in Google Cloud, and your install talks to YouTube directly, fully independent of Phoenix. Works today, and stays supported forever.

Uploads go straight to your channel through your own (free) Google Cloud OAuth client. Chain: Google account → Cloud project → OAuth client → refresh token → YouTube Data API.

1. Project and API

1. Open Google Cloud Console, create a project (any name).
2. APIs & Services → Library → enable YouTube Data API v3. Nothing else is needed — views and likes are read through the same API.

2. Consent screen

APIs & Services → OAuth consent screen:

• App name, support email, developer email — yours.
• Audience: External.
• While the app’s status is Testing, add your own Google account under Test users.

You do not need to hand-pick scopes here; the panel requests exactly three when you connect — youtube.upload to put a video up, youtube.readonly for the channel and the view counts, and youtube.force-ssl to take a video down again (uploading alone carries no right to delete).

3. OAuth client

1. APIs & Services → Credentials → Create credentials → OAuth client ID.
2. Application type: Web application.
3. Under Authorized redirect URIs add, verbatim, the redirect URI the panel shows in Settings → Connections → YouTube — for a local install that is http://127.0.0.1:8787/api/youtube/callback.
4. Create — copy the Client ID and Client secret into Settings → This install → YouTube, save.

4. Connect

Settings → Connections → YouTube → Connect via Google. Sign in with the account that owns the channel and allow both scopes. The service stores only the refresh token.

Google will warn that the app is unverified — that’s expected, it’s your app; Advanced → continue is the way through.

The three Google gotchas

• Testing mode expires tokens after 7 days. While the consent screen is in Testing, the refresh token dies weekly and you reconnect. Switch the app to In production (Audience page → Publish app) — verification is not required for that, only for removing the warning screen.
• The “private until verified” warning does not bite here. Google’s docs say unverified projects upload private-locked, but that restriction targets apps uploading to other people’s channels. With your own project and your own channel — exactly this setup — uploads come out with the visibility you picked.
• Quota allows roughly six uploads a day. An upload costs 1600 of the default 10 000 daily units. More than enough for a clips pipeline; batch imports come out of the same budget.

Storage (Cloudflare R2)

Any S3-compatible bucket works; R2 is the documented path (free tier covers a clips library). The bucket is where Instagram, TikTok and X download your video from — YouTube and Facebook publish fine without it.

1. In the Cloudflare dashboard open R2 and create a bucket — the panel expects phoenix-clips-media unless you change the Bucket name field.
2. Give it a public domain: bucket → Settings → Public access → Custom domains (or the r2.dev subdomain to start). This is Public URL of the bucket — it must serve files without a login.
3. Create credentials: R2 → Manage API tokens → Create API token, permission Object Read & Write, scoped to this bucket. The result is the Access key id and Secret access key — the secret is shown once.
4. The Account id is in the R2 sidebar; the S3 endpoint is https://<account-id>.r2.cloudflarestorage.com.

Six values total — all on Settings → This install → Storage.

Buffer (TikTok and X)

TikTok and X go through your own Buffer account: their direct APIs demand app audits and paid tiers that make no sense for an indie. Phoenix drives Buffer’s API; Buffer holds the platform logins.

The free plan is enough. Buffer’s free tier allows 3 connected channels — TikTok and X are two of them, leaving one spare. Two of its limits are worth knowing, because the panel reports them by name when they bite:

• 10 scheduled posts per channel at a time. Publishing right away doesn’t touch this; only a queue that has grown to ten waiting posts does. They free up as posts go out.
• 3000 API requests a month. Comfortable — the service refreshes metrics on a timer rather than polling, which is why the metrics interval and Buffer’s poll interval are settings and not something it decides on its own.

Paid plans (from $5/month per channel) lift the scheduling limit and add Buffer’s own analytics. Nothing in Phoenix Clips requires them.

1. Connect the TikTok and X accounts as channels inside Buffer itself.
2. Create an access token in your Buffer account’s developer/API settings and copy it, together with your organization id, into Settings → This install → Buffer.
3. The panel’s Connections tab then shows each platform matched to its Buffer channel automatically — the override map exists only for the rare account with duplicates.

AI captions (Anthropic)

Optional. The Generate button writes titles, captions and hashtags with Claude using your own key, billed by Anthropic per use — captions for a clip cost fractions of a cent.

1. Sign up at console.anthropic.com, open API keys, create one.
2. Paste it into Settings → This install → AI captions. Tone, language, base hashtags and the game’s name sit next to it.

Without a key the Generate button says it is not configured; nothing else cares.

Security, briefly

• Secrets never belong in git, screenshots, logs or support tickets.
• The panel masks stored secrets — it shows Set, never the value. Anything that leaks anyway can be revoked and re-issued in the console it came from; the panel takes a replacement in the same field.
• Grant only the scopes listed on this page. Nothing here needs messaging, comments moderation or ad permissions.