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

# Self-hosting the CLI auth server

> Run your own OAuth2 device-flow server for postiz auth:login

<Snippet file="audience/self-host-only.mdx" />

`postiz auth:login` uses the hosted auth server at `cli-auth.postiz.com` by
default. That works fine against a self-hosted Postiz too, since the server
only mediates the device flow. Run your own if you would rather no third party
sat in the login path.

The auth server mediates the OAuth2 device flow so CLI users can authenticate without needing client credentials of their own.

### Prerequisites

* Node.js >= 18
* PostgreSQL

### How It Works

```
CLI                        Auth Server                    Postiz
 |                              |                           |
 |-- 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 [postiz-agent](https://github.com/gitroomhq/postiz-agent) repository:

```bash theme={null}
git clone https://github.com/gitroomhq/postiz-agent.git
cd postiz-agent/server
```

### 2. Create an OAuth App in Postiz

Go to **Postiz 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/postiz_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 Postiz         |
| `POSTIZ_OAUTH_CLIENT_SECRET` | Yes      | -                             | OAuth app client secret from Postiz     |
| `PORT`                       | No       | `3111`                        | Server port                             |
| `SERVER_URL`                 | No       | `http://localhost:{PORT}`     | Public URL of this server               |
| `POSTIZ_FRONTEND_URL`        | No       | `https://platform.postiz.com` | Postiz frontend URL for OAuth redirects |
| `POSTIZ_API_URL`             | No       | `https://api.postiz.com`      | Postiz 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 POSTIZ_AUTH_SERVER="https://your-server-domain.com"
postiz 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 Postiz OAuth.                                   |
| `GET`  | `/device/callback` | Postiz 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.