OAuth2 (Recommended)
Authenticate using the device flow — no client ID or secret needed:
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 POSTIZ_API_KEY=your_api_key_here
OAuth2 credentials take priority over the API key when both are present.
Environment Variables
| Variable | Required | Default | Description |
|---|
POSTIZ_API_KEY | No* | - | Your SocialSyncs API key |
POSTIZ_API_URL | No | https://api.socialsyncs.co | Custom API endpoint (for self-hosted SocialSyncs) |
POSTIZ_AUTH_SERVER | No | https://cli-auth.socialsyncs.co | Custom auth server URL (for self-hosted auth server) |
socialsyncs auth:login) or POSTIZ_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
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-agent repository:
git clone https://github.com/lakshit77/socialsyncs-agent.git
cd socialsyncs-agent/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.
export DATABASE_URL="postgresql://user:password@localhost:5432/socialsyncs_auth"
export POSTIZ_OAUTH_CLIENT_ID="pca_xxx"
export POSTIZ_OAUTH_CLIENT_SECRET="pcs_xxx"
export SERVER_URL="https://your-server-domain.com"
| Variable | Required | Default | Description |
|---|
DATABASE_URL | Yes | - | Postgres connection string |
POSTIZ_OAUTH_CLIENT_ID | Yes | - | OAuth app client ID from SocialSyncs |
POSTIZ_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 |
POSTIZ_FRONTEND_URL | No | https://platform.socialsyncs.co | SocialSyncs frontend URL for OAuth redirects |
POSTIZ_API_URL | No | https://api.socialsyncs.co | 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 POSTIZ_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.