DocsSaaS Domain Management

SaaS Domain Management

Beta

Multi-tenant domain management API for SaaS applications with custom domains, automatic SSL, and dynamic routing.

This feature is in beta and will move to stable in Q2 2026. APIs may change before the stable release.

Features

Domain Verification

DNS TXT and HTTP challenge methods

Automatic SSL

ACME (Let's Encrypt) + manual upload

Dual Authentication

JWT + API Key support

Multi-tenant

Complete tenant isolation with quotas

Dynamic Routing

Per-domain routes without restart

Hot Reload

PostgreSQL NOTIFY for instant updates

Authentication

The SaaS API supports both JWT tokens and API keys for authentication.

JWT Authentication

Request with JWT
curl http://localhost:8080/api/v1/domains \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

API Key Authentication

Request with API Key
curl http://localhost:8080/api/v1/domains \
  -H "Authorization: ApiKey pk_live_abc123..."

API Endpoints

Domains

MethodEndpointDescription
GET/api/v1/domainsList domains
POST/api/v1/domainsAdd domain
GET/api/v1/domains/:idGet domain details
PUT/api/v1/domains/:idUpdate domain
DELETE/api/v1/domains/:idRemove domain
POST/api/v1/domains/:id/verifyTrigger verification
POST/api/v1/domains/:id/ssl/provisionProvision SSL via ACME
POST/api/v1/domains/:id/ssl/uploadUpload certificate

Routes & Upstreams

MethodEndpointDescription
POST/api/v1/domains/:id/routesCreate route
POST/api/v1/upstreamsCreate upstream
POST/api/v1/upstreams/:id/backendsAdd backend server

Domain Verification

DNS TXT Verification

Add a TXT record to prove domain ownership.

1. Add domain
curl -X POST http://localhost:8080/api/v1/domains \
  -H "Authorization: ApiKey pk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"domain": "app.example.com", "verification_method": "dns"}'
2. Create DNS TXT record
_postrust-verification.app.example.com TXT "postrust-verify=<token>"
3. Trigger verification
curl -X POST http://localhost:8080/api/v1/domains/<id>/verify \
  -H "Authorization: ApiKey pk_live_..."

SSL/TLS Certificates

Automatic ACME (Let's Encrypt)

curl -X POST http://localhost:8080/api/v1/domains/<id>/ssl/provision \
  -H "Authorization: ApiKey pk_live_..."

Manual Certificate Upload

curl -X POST http://localhost:8080/api/v1/domains/<id>/ssl/upload \
  -H "Authorization: ApiKey pk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "certificate": "-----BEGIN CERTIFICATE-----...",
    "private_key": "-----BEGIN PRIVATE KEY-----...",
    "chain": "-----BEGIN CERTIFICATE-----..."
  }'

Routing Configuration

Create upstream with backend
# Create upstream
curl -X POST http://localhost:8080/api/v1/upstreams \
  -H "Authorization: ApiKey pk_live_..." \
  -d '{"name": "api-backend", "lb_strategy": "round_robin"}'

# Add backend server
curl -X POST http://localhost:8080/api/v1/upstreams/<id>/backends \
  -H "Authorization: ApiKey pk_live_..." \
  -d '{"address": "10.0.0.1:8080", "scheme": "http"}'
Create route
curl -X POST http://localhost:8080/api/v1/domains/<domain_id>/routes \
  -H "Authorization: ApiKey pk_live_..." \
  -d '{
    "name": "api-route",
    "path_pattern": "/api",
    "path_type": "prefix",
    "upstream_id": "<upstream_id>",
    "strip_path": true
  }'

Load Balancing Strategies

round_robinDistribute requests evenly across backends
randomRandom backend selection
ip_hashConsistent hashing by client IP
least_connectionsRoute to least busy backend
weightedWeighted distribution based on backend weights

API Keys

Create API Key
curl -X POST http://localhost:8080/api/v1/auth/api-keys \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Key",
    "scopes": ["domains:read", "domains:write", "routes:write"],
    "expires_in_days": 365
  }'

Available Scopes

*Full access
domains:readRead domain information
domains:writeCreate/update/delete domains
routes:readRead routes
routes:writeCreate/update/delete routes
upstreams:readRead upstreams
upstreams:writeCreate/update/delete upstreams
api-keys:writeCreate/revoke API keys
Custom RoutesDeployment