> ## Documentation Index
> Fetch the complete documentation index at: https://docs.socialsyncs.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> Set up OAuth2 or API key authentication for the SocialSyncs CLI

## OAuth2 (Recommended)

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

```bash theme={null}
socialsyncs auth:login
```

This will:

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

### Auth Commands

```bash theme={null}
# 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:

```bash theme={null}
export SOCIALSYNCS_API_KEY=your_api_key_here
```

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

<Note>
  OAuth2 credentials take priority over the API key when both are present.
</Note>

## 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](https://github.com/lakshit77/socialsyncs-cli) repository:

```bash theme={null}
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

```bash theme={null}
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

```bash theme={null}
pnpm install

# Development
pnpm dev

# Production
pnpm build
pnpm start:prod
```

### 6. Point the CLI to Your Server

```bash theme={null}
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.