How Social Media Connections Work (OAuth 2.0)

When building an application like LogicSpike Content Engine that posts to user's social media accounts, the biggest question is: How do we connect their accounts? Do users need to generate their own API keys?

The short answer is NO. Users never have to create their own API keys or go to developer portals.

We use an industry-standard protocol called OAuth 2.0. This document explains exactly how it works.

1. The Core Concept: The "Master App"

As the developers of LogicSpike, WE create one "Master App" on each platform's developer portal (Twitter, LinkedIn, Facebook).

What We (LogicSpike) Do Once:

1. We go to the Facebook Developer Portal.
2. We click "Create New App" and name it "LogicSpike".
3. Facebook gives us two secret keys: a Client ID and a Client Secret.
4. We save these keys in our server's .env variables.

Analogy: The Client ID is our App's ID card. It proves to Facebook that this request is coming from LogicSpike, not some random hacker.

2. The User Journey: How a user connects their account

When a user in your dashboard clicks "Connect Facebook", here is exactly what happens, step-by-step:

Step 1: The Redirect (Authorization Request)

Our server generates a special link. It points to Facebook and includes our Client ID. It basically says: "Hey Facebook, I am LogicSpike (Client ID 123). Please ask the user for permission to read_pages and publish_posts."

The user's browser is redirected to this Facebook link.

Step 2: The Consent Screen (User Approves)

The user is now on facebook.com. They see a screen that says: "LogicSpike wants to access your account to: Read your Pages, Publish Posts."

The user clicks "Allow" or "Continue". (Notice: The user didn't need any API keys. They just logged into their normal Facebook account and clicked a button).

Step 3: The Callback (The Secret Code)

Because the user said "Yes", Facebook redirects the user back to our app (e.g., https://logicspike.com/api/auth/facebook/callback), and attaches a temporary Authorization Code in the URL. https://logicspike.com/.../callback?code=abc123xyz

Step 4: Exchanging the Code for a Token (Server-to-Server)

Our backend (Gateway or Content Engine) grabs that code. But the code is useless on its own. Our server makes a hidden, secure API call directly to Facebook's servers: "Hey Facebook, I am LogicSpike. Here is my secret password (Client Secret), and here is the temporary code the user just gave me."

Step 5: The Access Token

Facebook verifies everything and says: "Looks good! Here is an Access Token for this specific user."

Our database now saves this Access Token in the social_connections table.

3. How We Post Content Later

Two weeks later, the user schedules a post. How do we post it?

1. Our Cron Job wakes up and sees a post is due for User A on Facebook.
2. We look in our database and find the Access Token we saved in Step 5.
3. We send an API request to Facebook: "Hey Facebook, please publish this text. Oh, and here is User A's Access Token to prove we have permission."
4. Facebook sees the valid token and publishes the post instantly.

4. Summary: Who does what?

What happens if a token expires?

Some platforms (like Facebook and Twitter) issue Refresh Tokens alongside the Access Token. When an Access Token expires, our server uses the Refresh Token to automatically ask the platform for a new Access Token without bothering the user. If the user changes their password or completely revokes our app, we get an overarching "Revoked" error, and we must ask the user to click the "Connect" button again.

Terminology Glossary

• Client ID: Public identifier for our Master App.
• Client Secret: Private password for our Master App (must never be exposed to the frontend).
• Scopes: The specific permissions we ask the user for (e.g., "offline_access", "tweet.write").
• Access Token: The "VIP Pass" we get that allows us to post on behalf of that specific user.
• Refresh Token: A special key used to generate new Access Tokens when the old ones expire.