Skip to content

Feature Guide REST API

Jump to bottom
fuomag9 edited this page Apr 18, 2026 · 3 revisions

Feature Guide: REST API

Programmatic access to all Caddy Proxy Manager resources via a REST API.

Table of Contents

  1. Overview
  2. Authentication
  3. API Tokens
  4. Endpoints
  5. OpenAPI Documentation
  6. Examples

Overview

A full REST API is available under /api/v1/. It supports the same operations as the web UI: managing proxy hosts, certificates, access lists, settings, users, and more.

The interactive OpenAPI 3.1.0 specification is available at /api-docs in the web UI, or as raw JSON at /api/v1/openapi.json.

Authentication

The API supports two authentication methods:

Bearer token (recommended for automation)

curl -H "Authorization: Bearer <your-api-token>" \
  https://your-instance:3000/api/v1/proxy-hosts

Session cookie (browser)

If you are already logged in via the web UI, API requests from the same browser session are authenticated automatically.

API Tokens

Manage tokens from the API Tokens page (/api-tokens) or the Profile page.

Create a token

  1. Go to API Tokens or Profile.
  2. Enter a name and optional expiration date.
  3. Click Create.
  4. Copy the token immediately -- it is shown only once.

Token properties

Property Description
Name Human-readable label
Expiration Optional future date after which the token stops working
Last used Updated automatically (debounced to 60 seconds)

Tokens are stored as SHA-256 hashes in the database. The raw token cannot be recovered after creation.

Admin users can view and delete any token. Non-admin users can only manage their own tokens.

Endpoints

Resource Methods Path
Health GET /api/v1/health
Tokens GET, POST, DELETE /api/v1/tokens
Proxy Hosts GET, POST, PUT, DELETE /api/v1/proxy-hosts
L4 Proxy Hosts GET, POST, PUT, DELETE /api/v1/l4-proxy-hosts
Certificates GET, POST, PUT, DELETE /api/v1/certificates
CA Certificates GET, POST, PUT, DELETE /api/v1/ca-certificates
Client Certificates GET, POST, DELETE /api/v1/client-certificates
Client Cert Roles GET /api/v1/client-certificates/:id/roles
Access Lists GET, POST, PUT, DELETE /api/v1/access-lists
Access List Entries GET, POST, DELETE /api/v1/access-lists/:id/entries
Settings GET, POST /api/v1/settings/:group
Instances GET, POST, PUT, DELETE /api/v1/instances
Instance Sync POST /api/v1/instances/sync
Users GET, POST, PUT, DELETE /api/v1/users
Groups GET, POST, PATCH, DELETE /api/v1/groups
Group Members POST, DELETE /api/v1/groups/:id/members
mTLS Roles GET, POST, PUT, DELETE /api/v1/mtls-roles
mTLS Role Certs POST, DELETE /api/v1/mtls-roles/:id/certificates
mTLS Access Rules GET, POST, PUT, DELETE /api/v1/proxy-hosts/:id/mtls-access-rules
Forward Auth Access GET, PUT /api/v1/proxy-hosts/:id/forward-auth-access
Forward Auth Sessions GET, DELETE /api/v1/forward-auth-sessions
Audit Log GET /api/v1/audit-log
DNS Providers GET /api/v1/dns-providers
OAuth Providers GET, POST, PUT, DELETE /api/v1/oauth-providers
Caddy Apply POST /api/v1/caddy/apply

All endpoints return JSON. Error responses use standard HTTP status codes (400, 401, 403, 404, 500) with a JSON body containing a message field.

OpenAPI Documentation

The interactive API docs are available at /api-docs in the web UI. This page renders the full OpenAPI 3.1.0 specification with:

  • Try-it-out functionality for all endpoints
  • Request/response schema documentation
  • Authentication configuration

The raw spec is also available at /api/v1/openapi.json for code generation tools.

Examples

List all proxy hosts

curl -s -H "Authorization: Bearer $TOKEN" \
  https://your-instance:3000/api/v1/proxy-hosts | jq

Create a proxy host

curl -s -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My App",
    "domains": ["app.example.com"],
    "upstreams": ["10.0.0.5:8080"],
    "ssl_forced": true,
    "enabled": true
  }' \
  https://your-instance:3000/api/v1/proxy-hosts | jq

Apply Caddy configuration

curl -s -X POST -H "Authorization: Bearer $TOKEN" \
  https://your-instance:3000/api/v1/caddy/apply | jq

Get settings for a group

curl -s -H "Authorization: Bearer $TOKEN" \
  https://your-instance:3000/api/v1/settings/general | jq

Related Documentation

Need help? Open an issue with the request/response details (redact tokens and sensitive data).

Clone this wiki locally