Authentication

The PrintStudio API uses two authentication mechanisms: session cookies for the web dashboard and API keys for programmatic access.

API Key Authentication

All API requests from external clients must include the X-API-Key header:

curl http://localhost:8787/api/orders \
  -H "X-API-Key: psk_live_abc123..."

Generating API Keys

Via Dashboard

Go to Dashboard → Settings → API Keys → New Key. Set a name, expiry, and role (see below). The full key is shown once — copy it immediately.

Via API

# Requires an existing admin session or API key
curl -X POST http://localhost:8787/api/auth/api-keys \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-admin-key" \
  -d '{
    "name": "Production integration",
    "role": "operator",
    "expiresAt": "2025-12-31T00:00:00Z"
  }'

Response:

{
  "id": "key-uuid",
  "name": "Production integration",
  "key": "psk_live_abc123...",
  "role": "operator",
  "createdAt": "2024-01-15T10:00:00Z",
  "expiresAt": "2025-12-31T00:00:00Z"
}

Caution

The key field is only returned on creation. It is stored as a SHA-256 hash — there is no way to retrieve it later. Store it securely (e.g., in a secrets manager or CI/CD environment variable).

Roles (RBAC)

Role	Permissions
customer	Read own orders, create orders, view SKU catalog
operator	Full order/job management, printer control, inventory
admin	Everything + user management, API key management, system config

Endpoints that require elevated roles return 403 Forbidden if your key’s role is insufficient.

Session Authentication (Web Dashboard)

The web dashboard uses server-side sessions backed by Web Crypto SHA-256. Sessions are stored in a cookie (printstudio_session) with HttpOnly, SameSite=Strict, and Secure (in production).

# Login (returns Set-Cookie header)
curl -X POST http://localhost:8787/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{ "email": "operator@example.com", "password": "..." }' \
  -c cookies.txt

# Use session cookie for subsequent requests
curl http://localhost:8787/api/dashboard \
  -b cookies.txt

Revoking Keys

curl -X DELETE http://localhost:8787/api/auth/api-keys/{keyId} \
  -H "X-API-Key: your-admin-key"

Revoked keys return 401 Unauthorized immediately.

Key Format

API keys are prefixed to help distinguish environments and accidentally-committed secrets:

Prefix	Environment
psk_live_	Production
psk_test_	Development / test

Environment Variables

SESSION_SECRET=a-long-random-string-min-32-chars
API_KEY_SALT=another-random-string

Both are required. Generate with:

openssl rand -base64 32