Authentication

OAuth2 (Recommended)

Authenticate using the device flow — no client ID or secret needed:

socialsyncs auth:login

This will:

Display a one-time code in your terminal
Open your browser to authorize
Automatically save credentials to ~/.socialsyncs/credentials.json

Auth Commands

# Check current auth status (verifies credentials are still valid)
socialsyncs auth:status

# Remove stored credentials
socialsyncs auth:logout

API Key

Alternatively, set your SocialSyncs API key as an environment variable:

export SOCIALSYNCS_API_KEY=your_api_key_here

You can get your API key from the SocialSyncs Settings page.

OAuth2 credentials take priority over the API key when both are present.

Environment Variables

Variable	Required	Default	Description
`SOCIALSYNCS_API_KEY`	No*	-	Your SocialSyncs API key
`SOCIALSYNCS_API_URL`	No	`https://app.socialsyncs.co/api`	Custom API endpoint (for self-hosted SocialSyncs)
`SOCIALSYNCS_AUTH_SERVER`	No	`https://cli-auth.socialsyncs.co`	Custom auth server URL (for self-hosted auth server)

*Either OAuth2 (via socialsyncs auth:login) or SOCIALSYNCS_API_KEY is required.

Self-Hosting the Auth Server

By default, socialsyncs auth:login uses the hosted auth server at cli-auth.socialsyncs.co. If you want to self-host the OAuth2 device flow server, you can run your own instance. The auth server mediates the OAuth2 device flow so CLI users can authenticate without needing client credentials.

Prerequisites

Node.js >= 18
PostgreSQL

How It Works

CLI                        Auth Server                    SocialSyncs
 |                              |                           |
 |-- POST /device/code ------->|                           |
 |<-- device_code + user_code --|                           |
 |                              |                           |
 |  User opens browser ------->|                           |
 |  Enters code                |                           |
 |                              |-- redirect to OAuth ----->|
 |                              |<-- callback with code ----|
 |                              |-- exchange for token ---->|
 |                              |<-- access_token ----------|
 |                              |  (stored in Postgres)     |
 |                              |                           |
 |  POST /device/token (poll) >|                           |
 |<-- access_token ------------|                           |

1. Clone the Repository

The auth server lives in the socialsyncs-cli repository:

git clone https://github.com/lakshit77/socialsyncs-cli.git
cd socialsyncs-cli/server

2. Create an OAuth App in SocialSyncs

Go to SocialSyncs Settings > Developer > OAuth Apps and create a new app. Set the callback URL to:

https://your-server-domain.com/device/callback

3. Set Up Postgres

Create a database. The server auto-creates the device_requests table on startup.

4. Configure Environment

export DATABASE_URL="postgresql://user:password@localhost:5432/socialsyncs_auth"
export SOCIALSYNCS_OAUTH_CLIENT_ID="pca_xxx"
export SOCIALSYNCS_OAUTH_CLIENT_SECRET="pcs_xxx"
export SERVER_URL="https://your-server-domain.com"

Variable	Required	Default	Description
`DATABASE_URL`	Yes	-	Postgres connection string
`SOCIALSYNCS_OAUTH_CLIENT_ID`	Yes	-	OAuth app client ID from SocialSyncs
`SOCIALSYNCS_OAUTH_CLIENT_SECRET`	Yes	-	OAuth app client secret from SocialSyncs
`PORT`	No	`3111`	Server port
`SERVER_URL`	No	`http://localhost:{PORT}`	Public URL of this server
`SOCIALSYNCS_FRONTEND_URL`	No	`https://app.socialsyncs.co`	SocialSyncs frontend URL for OAuth redirects
`SOCIALSYNCS_API_URL`	No	`https://app.socialsyncs.co/api`	SocialSyncs API URL for token exchange

5. Run the Server

pnpm install

# Development
pnpm dev

# Production
pnpm build
pnpm start:prod

6. Point the CLI to Your Server

export SOCIALSYNCS_AUTH_SERVER="https://your-server-domain.com"
socialsyncs auth:login

Server Endpoints

Method	Path	Description
`POST`	`/device/code`	Start a new device flow. Returns `device_code`, `user_code`, and `verification_uri`.
`GET`	`/device/verify`	Browser page where the user enters their code.
`POST`	`/device/verify`	Validates user code and redirects to SocialSyncs OAuth.
`GET`	`/device/callback`	SocialSyncs redirects here after authorization. Exchanges auth code for token.
`POST`	`/device/token`	CLI polls this with `device_code`. Returns token when auth completes.
`GET`	`/health`	Health check.

Deployment

Any platform that runs Node.js and can connect to Postgres works — Railway, Fly.io, Render, VPS, etc. The server is stateless beyond Postgres, so it scales horizontally. Run multiple instances behind a load balancer if needed.

Getting Started

Usage

Examples

OAuth2 (Recommended)

Auth Commands

API Key

Environment Variables

Self-Hosting the Auth Server

Prerequisites

How It Works

1. Clone the Repository

2. Create an OAuth App in SocialSyncs

3. Set Up Postgres

4. Configure Environment

5. Run the Server

6. Point the CLI to Your Server

Server Endpoints

Deployment

​OAuth2 (Recommended)

​Auth Commands

​API Key

​Environment Variables

​Self-Hosting the Auth Server

​Prerequisites

​How It Works

​1. Clone the Repository

​2. Create an OAuth App in SocialSyncs

​3. Set Up Postgres

​4. Configure Environment

​5. Run the Server

​6. Point the CLI to Your Server

​Server Endpoints

​Deployment

OAuth2 (Recommended)

Auth Commands

API Key

Environment Variables

Self-Hosting the Auth Server

Prerequisites

How It Works

1. Clone the Repository

2. Create an OAuth App in SocialSyncs

3. Set Up Postgres

4. Configure Environment

5. Run the Server

6. Point the CLI to Your Server

Server Endpoints

Deployment