Social platform configuration (developer portals)

This guide is for platform administrators who configure Admin → Social Platform in SocialMine. It explains how to create an app in each provider’s developer console, which permissions (scopes) SocialMine requests, and what to paste into SocialMine.

Before you start: Set API_PUBLIC_URL in your root .env to the public base URL of your API (no /api suffix), for example https://api.yourdomain.com. SocialMine builds OAuth redirect (callback) URLs from this value. They must match exactly what you enter in each provider (including https, path, and no stray trailing slash unless your provider requires it).

Redirect URLs used by SocialMine

Your callback URL is usually:

{API_PUBLIC_URL}/api/connect/{platform}/callback

Replace {API_PUBLIC_URL} with the same value as in .env (no trailing slash). Use HTTPS in production.

In Admin → Social Platform → Configure, open the platform and use Copy on the Callback URL field if your deployment exposes it—this matches what the server computes.

You can override the callback per platform with a Callback URL field in the form only if you need a non-default value (advanced).

Facebook (Meta — Page posting)

SocialMine requests these permissions (scopes) for Facebook:

public_profile, email, pages_show_list, pages_read_engagement, pages_manage_posts

1. Meta Developer account

1. Go to Meta for Developers.
2. Sign in and open My Apps → Create App.
3. Choose a use case that supports Facebook Login and Pages (for example Manage everything on your Page or Other / Business type, depending on the wizard). Complete app name, contact email, and business portfolio if asked.

2. Add Facebook Login

1. In the app dashboard, add the Facebook Login product (Add products → Facebook Login → Set up).
2. Under Facebook Login → Settings, add Valid OAuth Redirect URIs:
   • Your SocialMine callback, e.g. https://api.yourdomain.com/api/connect/facebook/callback
3. Save changes.

3. App ID and secret

1. Settings → Basic: copy App ID and App Secret (click Show).
2. In SocialMine Configure Facebook, paste:
   • Client ID = App ID
   • Client Secret = App Secret
   • App Version (optional): e.g. v18.0 (must match Graph API versions your app supports).

4. Permissions and app mode

1. App Review → Permissions and Features: ensure the scopes above are available. Some require Advanced Access after app review for production.
2. While testing, keep the app in Development and add Test Users / roles as needed, or use a real admin account that owns the Page.
3. The Facebook user who connects must be able to manage the Facebook Page you post to. SocialMine uses the Page access flow implied by the Graph API for posting to the Page feed.

5. Common issues

• Redirect URI mismatch: URI in Meta must match the callback character-for-character.
• Invalid scopes: Add missing permissions in the Meta dashboard and complete review if required.

Instagram (Meta — Instagram Business / Creator)

SocialMine uses the Instagram Graph API (via Facebook Login). Scopes requested:

instagram_basic, instagram_manage_insights, instagram_content_publish, pages_show_list, pages_read_engagement

Prerequisites

• An Instagram Business or Creator account.
• That account linked to a Facebook Page you manage (Instagram → Settings → Account type and tools / Meta Business Suite).
• Often the same Meta app as Facebook is reused; you add the Instagram product.

1. Meta app

1. In Meta for Developers, open your app (or create one as for Facebook).
2. Add Instagram product if not present (Add Product → Instagram).

2. Facebook Login redirect

Instagram authorization uses the Facebook OAuth dialog. Under Facebook Login → Settings, add the Instagram callback URL:

https://your-api-host/api/connect/instagram/callback

(Same pattern as in the redirect table.)

3. Instagram permissions

1. In App Review → Permissions and Features, request:

   • instagram_basic
   • instagram_content_publish
   • instagram_manage_insights
   • Plus Page-related permissions used in the login flow (pages_show_list, pages_read_engagement).

2. For production users outside testers, you typically need Advanced Access after Meta review.

4. Credentials in SocialMine

In Configure Instagram:

• Client ID = Meta App ID
• Client Secret = Meta App Secret
• App Version = e.g. v18.0 (optional, defaults in code align with Graph version)

5. User reconnect / “Invalid Scopes”

If posting fails with permission errors, disconnect Instagram in SocialMine and connect again after updating scopes in the Meta app. Ensure instagram_content_publish is approved for your use case.

LinkedIn (member posting)

Scopes used by SocialMine:

openid, profile, email, w_member_social

1. LinkedIn Developer Portal

1. Go to LinkedIn Developers.
2. Create app: name, LinkedIn Page or company association, logo, legal agreement.

2. Auth and redirect

1. Open the app → Auth tab.

2. Under OAuth 2.0 settings, add Authorized redirect URLs for your app:

   https://your-api-host/api/connect/linkedin/callback

3. Copy Client ID and Client Secret from the same section (or Credentials).

3. Products / scopes

1. Products tab: enable what LinkedIn requires for sign-in and posting, for example:

   • Sign In with LinkedIn using OpenID Connect (covers openid, profile, email).
   • Share on LinkedIn / Advertising API is not required for basic member posts; w_member_social is the Share on LinkedIn / posting scope—enable the product that exposes Member content posting / w_member_social per current LinkedIn docs.

2. Request Marketing Developer Platform or posting access if LinkedIn gates w_member_social behind a product request.

4. SocialMine fields

• Client ID
• Client Secret
• Callback URL — only if you override the default (normally leave blank so the server uses API_PUBLIC_URL).

X (Twitter) — OAuth 2.0 with PKCE

SocialMine uses OAuth 2.0 Authorization Code with PKCE (not legacy OAuth 1.0a for the connect flow). Scopes:

tweet.read, tweet.write, users.read, offline.access

1. Developer portal

1. Go to the X Developer Portal (or developer.x.com).
2. Create a Project and a Standalone App (or app under a project) with User authentication enabled.

2. OAuth 2.0 settings

1. Open your app → User authentication settings → Set up (or Edit).

2. App permissions: at minimum Read and write (so tweet.write is allowed).

3. Type of App: Web App (or Confidential client if offered—SocialMine uses a server-side token exchange with Client Secret).

4. Callback URI / Redirect URL: add

   https://your-api-host/api/connect/twitter/callback

   Note: the path uses twitter, not x.

5. Save.

3. Keys

1. Keys and tokens (or Credentials):

   • OAuth 2.0 Client ID and Client Secret — required for SocialMine.

2. In Configure X (Twitter) in SocialMine, set:

   • Client ID = OAuth 2.0 Client ID
   • Client Secret = OAuth 2.0 Client Secret

   Other fields in the form (API Key, legacy tokens) are not used by the OAuth 2.0 connect flow in the current backend; you can leave them empty unless you use them elsewhere.

4. Elevated access

Posting may require Elevated or appropriate X API access tier—check current X pricing and policy.

TikTok (Login Kit + Content Posting API)

Scopes used:

user.info.basic, user.info.profile, video.publish

1. TikTok for Developers

1. Go to TikTok for Developers.
2. Register and open Developer Portal → Manage apps → Create an app (or connect an existing one).

2. App configuration

1. Configure Login Kit (or OAuth): set Redirect URI / Authorized redirect URLs to:

   https://your-api-host/api/connect/tiktok/callback

2. Ensure scopes for user info and video.publish (or Content Posting) are requested per TikTok’s current scope names—SocialMine sends the scopes listed above; align your TikTok app’s approved scopes with them.

3. Copy Client key and Client secret from the app.

3. SocialMine fields

• Client Key → maps to Client Key in the form (clientId in config).
• Client Secret → Client Secret.

4. Notes

• TikTok may require app review before production posting.
• Some video flows open the TikTok app for final confirmation—behavior can depend on TikTok’s API version and media type.

Threads (Meta)

Scopes used:

threads_basic, threads_content_publish, threads_delete

1. Meta / Threads developer setup

1. Threads API is accessed through Meta for Developers (Threads uses threads.net OAuth endpoints in SocialMine).

2. Create or select an app. Add the Threads use case / product per Meta’s current Threads API documentation.

3. Configure Redirect URIs / Valid OAuth Redirect URIs for Threads to include:

   https://your-api-host/api/connect/threads/callback

2. Credentials

• Client ID and Client Secret from the Meta app settings (same style as other Meta apps).

3. Review

Threads permissions may require App Review and a verified business for broad access—check Meta’s latest Threads API terms.

After configuration in SocialMine

1. Save Configure for each platform with Client ID and Client Secret (and App Version for Meta where used).
2. Turn the platform On only after values are saved.
3. As an end user, open Social Profile in the tenant app, choose the network, and Connect to run OAuth.
4. If anything fails, compare the exact callback URL from the admin modal with the developer console, and confirm API_PUBLIC_URL matches how users reach your API (no wrong port, HTTP vs HTTPS, or reverse proxy path).

Quick reference — scopes implemented in SocialMine

If your admin form supports a custom scope field for a platform, it overrides these defaults—only change it if you know the provider accepts the exact scope string you enter.