Skip to main content

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.

Authenticate using the device flow — no client ID or secret needed: 
postiz auth:login
This will:
  1. Display a one-time code in your terminal
  2. Open your browser to authorize
  3. Automatically save credentials to ~/.postiz/credentials.json

​
Auth Commands

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

# Remove stored credentials
postiz auth:logout

​
API Key

Alternatively, set your Postiz API key as an environment variable: 
export POSTIZ_API_KEY=your_api_key_here
You can get your API key from the Postiz Settings page.
OAuth2 credentials take priority over the API key when both are present.

​
Environment Variables

VariableRequiredDefaultDescription
POSTIZ_API_KEYNo*-Your Postiz API key
POSTIZ_API_URLNohttps://api.postiz.comCustom API endpoint (for self-hosted Postiz)
POSTIZ_AUTH_SERVERNohttps://cli-auth.postiz.comCustom auth server URL (for self-hosted auth server)
*Either OAuth2 (via postiz auth:login) or POSTIZ_API_KEY is required.

​
Self-Hosting the Auth Server

By default, postiz auth:login uses the hosted auth server at cli-auth.postiz.com. 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                    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"
VariableRequiredDefaultDescription
DATABASE_URLYes-Postgres connection string
POSTIZ_OAUTH_CLIENT_IDYes-OAuth app client ID from Postiz
POSTIZ_OAUTH_CLIENT_SECRETYes-OAuth app client secret from Postiz
PORTNo3111Server port
SERVER_URLNohttp://localhost:{PORT}Public URL of this server
POSTIZ_FRONTEND_URLNohttps://platform.postiz.comPostiz frontend URL for OAuth redirects
POSTIZ_API_URLNohttps://api.postiz.comPostiz 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

MethodPathDescription
POST/device/codeStart a new device flow. Returns device_code, user_code, and verification_uri.
GET/device/verifyBrowser page where the user enters their code.
POST/device/verifyValidates user code and redirects to Postiz OAuth.
GET/device/callbackPostiz redirects here after authorization. Exchanges auth code for token.
POST/device/tokenCLI polls this with device_code. Returns token when auth completes.
GET/healthHealth 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.