Developer App Setup

Before users can connect social accounts through Social Publishing, an administrator must create OAuth apps on each platform's developer portal and enter the credentials in KronGage Settings. This gives your workspace full control over rate limits and data access.

---

How Credentials Work

OAuth credentials are stored per organisation in the KronGage database, encrypted with AES-256. They are never shared across tenants.

Tenant Admin
  └─ goes to web.krongage.io/settings → "Social Publishing API Keys"
       └─ enters Client ID + Client Secret (+ optional Redirect URI)
            └─ saved encrypted under their organisation
                 └─ Postiz uses them at OAuth time → passed to provider

Do not put OAuth Client IDs or Secrets in any .env file. All credential fields should be entered per-tenant via Settings.

---

Redirect URI Convention

For every platform, the OAuth redirect URI follows this pattern:

https://web.krongage.io/postiz/integrations/social/{provider-slug}

Two exceptions — X/Twitter and Threads use the base domain without /postiz:

https://web.krongage.io/integrations/social/x
https://web.krongage.io/integrations/social/threads

Multi-tenant note: Even if your workspace is at test.krongage.io, the OAuth redirect URI always points to web.krongage.io/postiz/…. Postiz is deployed there, and a returnURL query param routes the user back to their tenant subdomain after auth completes. If a tenant brings their own OAuth app with a custom domain, they can override the Redirect URI in Settings — that value takes precedence.

---

Where to Enter Credentials

Go to KronGage → Settings → Social Publishing API Keys.

For each platform enter:

---

1. Facebook Page

Posts text, photos, carousels, and videos to a Facebook Page.

Developer Console Setup:

1. Go to developers.facebook.com → My Apps → Create App, choose Business
2. Add the Facebook Login product
3. In Facebook Login → Settings → Valid OAuth Redirect URIs, add:

   https://web.krongage.io/postiz/integrations/social/facebook

4. Required permissions: pages_show_list, business_management, pages_manage_posts, pages_manage_engagement, pages_read_engagement, read_insights

KronGage Settings:

Known issues:

• Page selector appears blank — the Facebook user who authorises must have admin access to at least one Page
• Token expires after ~60 days — normal; reconnect from Channels

---

2. Instagram Business

Posts feed images, carousels, Reels, and Stories. Uses the same Meta app as Facebook.

Developer Console Setup:

1. In your existing Facebook App (from step 1 above), add the Instagram Graph API product
2. In Instagram → Basic Display → Valid OAuth Redirect URIs, add:

   https://web.krongage.io/postiz/integrations/social/instagram

3. Required permissions: instagram_basic, pages_show_list, pages_read_engagement, business_management, instagram_content_publish, instagram_manage_comments, instagram_manage_insights
4. The Instagram account must be a Business or Creator account connected to a Facebook Page

KronGage Settings:

Known issues:

• "No Instagram account found" — the Facebook user must have connected their Instagram Business account to their Facebook Page in Instagram settings
• Carousel size error — images must be between 4:5 and 1.91:1 aspect ratio

---

3. Instagram Standalone (Personal)

Posts feed images, carousels, and Reels. Uses a separate app from Facebook — the Instagram Platform API.

Developer Console Setup:

1. Go to developers.facebook.com → Create a separate app, type: Consumer
2. Add the Instagram Platform product
3. In Instagram Platform → API Setup with Instagram Login, add redirect URI:

   https://web.krongage.io/postiz/integrations/social/instagram-standalone

4. Required permissions: instagram_business_basic, instagram_business_content_publish, instagram_business_manage_comments, instagram_business_manage_insights

KronGage Settings:

---

4. Threads

Posts text to Threads. Can use the same Facebook app or a separate one.

Developer Console Setup:

1. In your Meta app, add the Threads API product
2. In Threads API → Redirect URIs, add:

   https://web.krongage.io/integrations/social/threads

   Note: no /postiz prefix — Threads uses the base domain like X/Twitter.

3. Required permissions: threads_basic, threads_content_publish, threads_manage_replies, threads_manage_insights

KronGage Settings:

Known issues:

• Redirect URI mismatch — the URI must NOT have /postiz. Threads uses the base domain URL, unlike all other Meta providers.

---

5. X / Twitter

Posts tweets, threads, and media. Uses OAuth 1.0a — not OAuth 2.0.

X credentials must be configured in Settings. There is no global fallback — the app will throw an error for all users if not set.

Developer Console Setup:

1. Go to developer.twitter.com and create or select an app in a Project
2. In App Settings → User authentication settings:
   • Enable OAuth 1.0a, set permissions to Read and Write
   • Callback URL: https://web.krongage.io/integrations/social/x ← no /postiz
   • Website URL: https://web.krongage.io
3. In Keys and Tokens, copy the API Key and API Key Secret
4. Request Elevated access if you need analytics

KronGage Settings:

Known issues:

• "X API credentials are not configured" — X has no fallback. You must configure credentials before any user can connect an X account.
• Redirect URI must match exactly — no trailing slash; copy as shown.

---

6. LinkedIn (Personal)

Posts text, articles, images, and single videos to a personal profile.

Developer Console Setup:

1. Go to linkedin.com/developers → Create App (requires association with a LinkedIn Company Page)
2. In Auth tab → Authorized Redirect URLs, add:

   https://web.krongage.io/postiz/integrations/social/linkedin

3. In Products tab, request:
   • Sign In with LinkedIn using OpenID Connect
   • Share on LinkedIn
     (provides scopes: openid, profile, w_member_social)
4. Copy Client ID and Client Secret from the Auth tab

KronGage Settings:

Known issues:

• Carousel posts — LinkedIn doesn't support native carousels; Postiz converts them to PDF, requiring LibreOffice on the server.
• Token TTL is 59 days — reconnect required after ~2 months.

---

7. LinkedIn Page (Company)

Posts on behalf of a LinkedIn Company Page. Uses the same LinkedIn app as personal.

Developer Console Setup:

Same app as LinkedIn Personal. Additionally request the Marketing Developer Platform product, which provides: rw_organization_admin, w_organization_social, r_organization_social

Add redirect URI:

https://web.krongage.io/postiz/integrations/social/linkedin-page

KronGage Settings:

---

8. YouTube

Uploads videos with descriptions and thumbnails.

Developer Console Setup:

1. Go to console.cloud.google.com and create or select a project
2. Enable YouTube Data API v3 and YouTube Analytics API
3. Go to Credentials → Create Credentials → OAuth 2.0 Client ID, type: Web application
   • Authorized JavaScript Origins: https://web.krongage.io
   • Authorized Redirect URIs: https://web.krongage.io/postiz/integrations/social/youtube
4. Go to OAuth consent screen, add scopes: youtube, youtube.force-ssl, youtube.readonly, youtube.upload, yt-analytics.readonly
5. If app is in Testing mode: go to Test users and add every Gmail address that needs to connect

KronGage Settings:

Known issues:

• "Access blocked: krongage.io has not completed verification" — app is in Testing mode; add the Google account email as a Test User in the OAuth consent screen.
• Google OAuth blocked in iframe — handled automatically by KronGage; the OAuth URL opens in the top-level browser window via a postMessage relay.

---

9. Google My Business (GMB)

Posts updates, offers, and events to a Google Business Profile.

You can use the same Google Cloud OAuth client as YouTube — just add the GMB redirect URI alongside the YouTube one.

Developer Console Setup:

1. In your Google Cloud project, enable Google My Business API and Business Profile Performance API
2. In your OAuth 2.0 Client, add:
   • Authorized Redirect URIs: https://web.krongage.io/postiz/integrations/social/gmb
   • Authorized JavaScript Origins: https://web.krongage.io

KronGage Settings:

---

10. TikTok

Posts videos and photo slideshows.

Developer Console Setup:

1. Go to developers.tiktok.com → Manage Apps → Create App
2. Add Login Kit product
3. In Login Kit → Redirect URI Allowlist, add:

   https://web.krongage.io/postiz/integrations/social/tiktok

4. Scopes: video.list, user.info.basic, video.publish, video.upload, user.info.profile, user.info.stats
5. Copy Client Key (= Client ID) and Client Secret

KronGage Settings:

Known issues:

• Token expires every 23 hours — normal; Postiz auto-refreshes via cron job.
• "Content settings" error — flags like disable_duet, disable_stitch, disable_comment are set automatically by the provider.

---

11. Pinterest

Pins images and videos to boards.

Developer Console Setup:

1. Go to developers.pinterest.com → Create App
2. In App Settings → Redirect URIs, add:

   https://web.krongage.io/postiz/integrations/social/pinterest

3. Scopes: boards:read, boards:write, pins:read, pins:write, user_accounts:read
4. Copy App ID (= Client ID) and App Secret Key (= Client Secret)

KronGage Settings:

---

12. Reddit

Posts links, text, images, and videos to subreddits.

Developer Console Setup:

1. Go to reddit.com/prefs/apps → Create Another App, type: web app
2. Redirect URI: https://web.krongage.io/postiz/integrations/social/reddit
3. Scopes used: read, identity, submit, flair
4. Copy the App ID (shown below the app name) and Secret

KronGage Settings:

Known issues:

• Rate limit: 1 req/sec — Reddit enforces strict throttling; max 1 concurrent post job.

---

13. Discord

Posts messages to Discord channels via a bot.

Discord requires a Bot Token in addition to OAuth credentials. The bot must be added to the server with message permissions. The Bot Token is infrastructure config — set once by the platform admin in .env, not per-org.

Developer Console Setup:

1. Go to discord.com/developers/applications → New Application
2. In OAuth2 → Redirects, add:

   https://web.krongage.io/postiz/integrations/social/discord

3. In Bot tab: enable the bot and copy the Bot Token (set as DISCORD_BOT_TOKEN_ID in .env)
4. Bot permissions: Send Messages, Embed Links, Attach Files, Read Message History
5. OAuth2 scopes: bot, applications.commands

KronGage Settings:

---

14. Slack

Posts messages to Slack channels.

The Slack Signing Secret is infrastructure config (SLACK_SIGNING_SECRET in .env) — not a per-org credential.

Developer Console Setup:

1. Go to api.slack.com/apps → Create New App → From scratch
2. In OAuth & Permissions → Redirect URLs, add:

   https://web.krongage.io/postiz/integrations/social/slack

3. Add Bot Token Scopes: chat:write, channels:read, groups:read
4. Install the app to your workspace and copy Client ID and Client Secret

KronGage Settings:

---

15. Mastodon

Posts toots (text and media) to a Mastodon instance.

Mastodon is unique — each instance is independent. You register an OAuth app on your specific Mastodon instance. The Instance URL must be stored in Settings.

Developer Console Setup:

1. Go to your Mastodon instance (e.g. https://mastodon.social)
2. Navigate to Preferences → Development → New Application
3. Redirect URI: https://web.krongage.io/postiz/integrations/social/mastodon
4. Scopes: write:statuses, read:accounts, write:media
5. Copy the generated Client ID and Client Secret

KronGage Settings:

---

16. Dribbble

Posts design shots.

Developer Console Setup:

1. Go to dribbble.com/account/applications → New Application
2. Callback URL: https://web.krongage.io/postiz/integrations/social/dribbble
3. Copy Client ID and Client Secret

KronGage Settings:

---

17. Twitch

Posts channel updates and announcements.

Developer Console Setup:

1. Go to dev.twitch.tv/console/apps → Register Your Application
2. OAuth Redirect URLs: https://web.krongage.io/postiz/integrations/social/twitch
3. Category: Website Integration
4. Copy Client ID and Client Secret (generate from the app page)

KronGage Settings:

---

18. VK (VKontakte)

Posts wall posts, text, and images.

Developer Console Setup:

1. Go to vk.com/dev → My apps → Create
2. Authorized redirect URI: https://web.krongage.io/postiz/integrations/social/vk
3. Copy App ID (= Client ID) and Secure key (= Client Secret)

KronGage Settings:

---

19. Bluesky

Posts text and media. Does not use OAuth — uses an App Password instead.

Setup:

1. In your Bluesky account, go to Settings → Privacy and Security → App Passwords → Add App Password
2. Name it (e.g. "KronGage") and copy the generated password

Connecting in KronGage:

When adding Bluesky as a channel, enter:

• Service URL: https://bsky.social (or your custom PDS URL)
• Identifier: Your Bluesky handle or email
• Password: The App Password you generated

No OAuth app or credentials in Settings required.

---

20. Medium

Posts articles and stories using an Integration Token.

1. In Medium, go to Settings → Security → Integration tokens
2. Generate a new token
3. Paste it when adding Medium as a channel in KronGage

---

21. Dev.to

Posts technical articles using an API Key.

1. In Dev.to, go to Settings → Extensions → DEV Community API Keys
2. Generate a new key
3. Paste it when adding Dev.to as a channel in KronGage

---

22. Hashnode

Posts technical blog articles using a Personal Access Token.

1. In Hashnode, go to Settings → Developer → Access Tokens
2. Generate a token
3. Paste it when adding Hashnode as a channel in KronGage

---

Quick Reference: All Redirect URIs

---

Multi-Tenancy Checklist

When a new tenant onboards (e.g. acme.krongage.io):

• Tenant admin goes to web.krongage.io/settings → Social Publishing API Keys
• For each social channel they want to use:
  • Create an OAuth app in the provider's developer console
  • Register https://web.krongage.io/postiz/integrations/social/{provider} as the redirect URI
  • Enter Client ID and Client Secret in KronGage Settings
• For YouTube: add each Google account email as a Test User in the OAuth consent screen (or submit app for Google verification for production use)
• For X: credentials must be configured — there is no global fallback
• Connect channels via Social Publishing → Channels → Add Channel