OAuth overview

How platform connections are configured, and what each platform requires before it will publish.

SocialRelay never asks anyone for a social media password. Each platform is connected through its own OAuth flow: you register a developer application once, put its credentials in the server environment, and from then on every connection is a single Connect button on the Social Accounts screen.

Credentials never appear in the interface

Client IDs and secrets are read from the server environment only. They are never rendered in a page, never sent to the browser, and there is no screen for entering them. Access and refresh tokens are encrypted before they are written to the database.

Who this page is for

This is administrator documentation — for whoever deploys SocialRelay. If you just want to connect your own account to an instance someone else runs, go to Social accounts instead.

Redirect URIs

Every provider requires you to register the exact URL it will send the browser back to. These must match character for character, including the scheme and any trailing path.

text

https://social.aitoolbucket.com/api/oauth/facebook/callback
https://social.aitoolbucket.com/api/oauth/instagram/callback
https://social.aitoolbucket.com/api/oauth/tiktok/callback
https://social.aitoolbucket.com/api/oauth/x/callback

If you also enable Google sign-in for the application itself, register this one with Google:

text

https://social.aitoolbucket.com/api/auth/callback/google

Local development uses a different origin

Running locally, the origin is http://localhost:3001. Most providers let you register several redirect URIs on one app, so you can add both. TikTok and X are stricter about non-HTTPS origins — see their individual pages.

Scopes this application requests

These are the exact scopes in the code. Requesting more than an application needs slows down platform review, so this list is deliberately minimal.

Platform	Scopes
Facebook	`pages_show_list`, `pages_read_engagement`, `pages_manage_posts`, `business_management`
Instagram	`instagram_basic`, `instagram_content_publish`, `pages_show_list`, `pages_read_engagement`, `business_management`
TikTok	`user.info.basic`, `video.publish`, `video.upload`
X	`tweet.read`, `tweet.write`, `users.read`, `media.write`, `offline.access`

Environment variables

bash

# Meta covers both Facebook and Instagram — one app, one pair of credentials.
FACEBOOK_CLIENT_ID="..."
FACEBOOK_CLIENT_SECRET="..."

# Optional. Only set these if Instagram uses a different Meta app;
# otherwise it falls back to the Facebook values above.
INSTAGRAM_CLIENT_ID=""
INSTAGRAM_CLIENT_SECRET=""

TIKTOK_CLIENT_KEY="..."
TIKTOK_CLIENT_SECRET="..."

X_CLIENT_ID="..."
X_CLIENT_SECRET="..."

# Real publishing happens only when this is not "true".
SOCIAL_MOCK_MODE="false"

Installing secrets without exposing them

Do not paste a client secret into a chat window, a ticket, or a shell command that lands in your history. Read them in at a prompt instead:

bash

# Run this on the server. Paste each secret at the prompt so it never
# appears in your shell history, in a chat, or in a process list.
cd /var/www/creator

read -rsp "X_CLIENT_ID: " V && printf '\nX_CLIENT_ID="%s"\n' "$V" >> .env
read -rsp "X_CLIENT_SECRET: " V && printf '\nX_CLIENT_SECRET="%s"\n' "$V" >> .env

sudo systemctl restart creator-app creator-worker

If a secret is ever exposed, rotate it

Treat a secret that has appeared in a chat log, a screenshot, or a git commit as compromised. Every provider lets you regenerate one from its dashboard; doing so invalidates the old value immediately.

Mock mode

Until credentials exist, keep SOCIAL_MOCK_MODE="true". Connecting then creates a simulated account and publishing returns fake post IDs, so the entire workflow — review, approval, scheduling, retries, the activity log — can be exercised before any developer application is approved.

Real publishing happens only when the flag is not true. It is never faked implicitly, and the interface shows a persistent notice whenever mock mode is on so it cannot be left enabled by accident.

Platform review

All three providers gate publishing behind some form of review. Roughly what to expect:

Platform	Before review	What review unlocks
Meta	Works for Pages owned by users with a role on the app	Publishing to Pages owned by anyone else
TikTok	Posts are restricted to private or self-only visibility	Publicly visible posts
X	Posting works immediately, subject to plan rate limits	Higher volume, via a paid access tier

That means X is the fastest platform to get a genuinely real post out of, which makes it a good first one to configure.

Set up a platform

X setup — quickest path to a real post
Meta setup — Facebook and Instagram
TikTok setup — photo posts