Skip to main content
UpNext uses an optional single bearer token to protect the self-hosted dashboard and REST API. Authentication is opt-in for local development and self-hosted deployments.

​
Self-hosted authentication

Set two environment variables when starting the server:
Backend-first: choose UPNEXT_BACKEND before startup. This example uses sqlite.
UPNEXT_AUTH_ENABLED=true \
UPNEXT_API_KEY=your-secret-key \
UPNEXT_BACKEND=sqlite \
UPNEXT_DATABASE_URL=sqlite+aiosqlite:///upnext.db \
UPNEXT_REDIS_URL=redis://localhost:6379 \
upnext server start --port 8080
When enabled, UPNEXT_API_KEY becomes the one bearer token accepted by the self-hosted runtime.

​
How it works

When self-hosted authentication is enabled:
  1. Every request to /api/v1/* must include an Authorization: Bearer <key> header
  2. The runtime compares the provided token to UPNEXT_API_KEY
  3. If the token matches, the request proceeds
  4. If the token is missing or invalid, the server returns 401
When authentication is disabled, all endpoints are open and no headers are required for self-hosted use.

​
Connect workers and APIs

Workers and APIs need the same self-hosted token to report to the dashboard. Set UPNEXT_API_KEY alongside UPNEXT_URL: 
UPNEXT_URL=http://localhost:8080 \
UPNEXT_API_KEY=your-secret-key \
UPNEXT_REDIS_URL=redis://localhost:6379 \
upnext run service.py
The same token gates the dashboard and API. There is nothing to provision inside the runtime itself.

​
Verify a key

Check if a key is valid without performing any action: 
curl -X POST http://localhost:8080/api/v1/auth/verify \
  -H "Authorization: Bearer your-key"
Returns 200 with the resolved workspace scope if valid, 401 if invalid.

​
Check auth status

Check whether the server has authentication enabled (no key required): 
curl http://localhost:8080/api/v1/auth/status

{"auth_enabled": true, "runtime_mode": "self_hosted"}

​
Environment variables

VariableDefaultDescription
UPNEXT_AUTH_ENABLEDfalseEnable the self-hosted bearer-token gate
UPNEXT_API_KEY—Static bearer token for self-hosted auth