Self-hosting the CLI auth server

Self-hosted only. This page describes configuration you do on your own Postiz instance. On Postiz Cloud it is already handled for you, so nothing here applies.

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 repository:

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

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

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"
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.

Self-hosting the CLI auth server

On this page