API Documentation

All API endpoints require authentication via the auth-token header unless otherwise noted.

Base URL: https://your-proxy-host.com/api

Authentication

POST /api/auth/login

Authenticate a user and receive an auth token.

curl -H "Content-Type: application/json" \
  -X POST \
  -d '{"username": "myuser", "password": "mypassword"}' \
  https://proxy-host.com/api/auth/login

Responses:

200 {"login": true, "token": "027d3964-7d81-4462-a6f9-2c1f9b40b4be", "message": "myuser logged in!"}
401 {"name": "LoginFailed", "message": "Invalid Credentials, login failed."}

Logout

ALL /api/auth/logout

Invalidate the current auth token.

curl -H "auth-token: your-token-here" \
  -X POST \
  https://proxy-host.com/api/auth/logout

Responses:

200 {"message": "Bye"}

Users

All user endpoints require authentication.

List Users

GET /api/user

Get list of all users.

curl -H "auth-token: your-token-here" \
  https://proxy-host.com/api/user

Query Parameters:

detail - Include full user details (optional)

Responses:

200 {"results": ["user1", "user2"]}
200 {"results": [{"username": "user1", ...}, ...]} (with ?detail=true)

Get Current User

GET /api/user/me

Get information about the currently authenticated user.

curl -H "auth-token: your-token-here" \
  https://proxy-host.com/api/user/me

Responses:

200 {"username": "myuser"}

Create User

POST /api/user

Create a new user.

curl -H "Content-Type: application/json" \
  -H "auth-token: your-token-here" \
  -X POST \
  -d '{"username": "newuser", "password": "newpassword"}' \
  https://proxy-host.com/api/user

Responses:

200 User created successfully
409 Username already exists
422 {"name": "ObjectValidateError", "message": ...} Validation error

Delete User

DELETE /api/user/:username

Delete a user account.

curl -H "auth-token: your-token-here" \
  -X DELETE \
  https://proxy-host.com/api/user/olduser

Responses:

200 {"username": "olduser", "results": ...}
404 User not found

Change Password (Self)

PUT /api/user/password

Change the password for the currently authenticated user.

curl -H "Content-Type: application/json" \
  -H "auth-token: your-token-here" \
  -X PUT \
  -d '{"password": "newpassword"}' \
  https://proxy-host.com/api/user/password

Responses:

200 {"results": ...} Password changed successfully

Change Password (Other User)

PUT /api/user/password/:username

Change the password for another user (admin function).

curl -H "Content-Type: application/json" \
  -H "auth-token: your-token-here" \
  -X PUT \
  -d '{"password": "newpassword"}' \
  https://proxy-host.com/api/user/password/otheruser

Responses:

200 {"results": ...} Password changed successfully
404 User not found

Create Invite Token

POST /api/user/invite

Create an invitation token for new user registration.

curl -H "auth-token: your-token-here" \
  -X POST \
  https://proxy-host.com/api/user/invite

Responses:

200 {"token": "5caf94d2-2c91-4010-8df7-968d10802b9d"}

Add SSH Key

POST /api/user/key

Add an SSH public key to the current user’s account.

curl -H "Content-Type: application/json" \
  -H "auth-token: your-token-here" \
  -X POST \
  -d '{"key": "ssh-rsa AAAAB3..."}' \
  https://proxy-host.com/api/user/key

Responses:

200 {"message": true} Key added successfully
400 {"message": "Bad SSH key"} Invalid key format

Hosts

Manage proxy host configurations.

List Hosts

GET /api/host

Get list of all configured hosts.

curl -H "auth-token: your-token-here" \
  https://proxy-host.com/api/host

Query Parameters:

detail - Include full host details (optional)

Responses:

200 {"results": ["example.com", "*.wildcard.com"]}
200 {"results": [{"host": "example.com", "ip": "192.168.1.10", ...}, ...]} (with ?detail=true)

Get Host

GET /api/host/:host

Get configuration for a specific host.

curl -H "auth-token: your-token-here" \
  https://proxy-host.com/api/host/example.com

Responses:

200 {"item": "example.com", "results": {"host": "example.com", "ip": "192.168.1.10", "targetPort": 8080, ...}}
404 {"name": "HostNotFound", "message": "Host does not exists"}

Lookup Host

GET /api/host/lookup/:domain

Test the host lookup algorithm (supports wildcard matching).

curl -H "auth-token: your-token-here" \
  https://proxy-host.com/api/host/lookup/sub.example.com

Responses:

200 {"string": "sub.example.com", "results": {"host": "*.example.com", ...}}
200 {"string": "sub.example.com", "results": null} (no match)

Get Lookup Tree

GET /api/host/lookupobj

Get the internal lookup tree structure (for debugging).

curl -H "auth-token: your-token-here" \
  https://proxy-host.com/api/host/lookupobj

Responses:

200 {"results": {"com": {"example": {...}}}}

Create Host

POST /api/host

Add a new host configuration.

Parameters:

host (required) - Domain name (e.g., example.com, *.example.com)
ip (required) - Target IP address or FQDN
targetPort (required) - Target port number (1-65535)
forcessl (optional) - Force HTTPS redirect (default: true)
targetssl (optional) - Use HTTPS to backend (default: false)
challengeType (optional) - For wildcards: DNS-01-wildcard or wildcardChild

curl -H "Content-Type: application/json" \
  -H "auth-token: your-token-here" \
  -X POST \
  -d '{"host": "example.com", "ip": "192.168.1.10", "targetPort": 8080, "forcessl": true, "targetssl": false}' \
  https://proxy-host.com/api/host

Responses:

200 {"message": "\"example.com\" added.", "host": "example.com", ...}
409 {"name": "HostNameUsed", "message": "Host already exists"}
422 {"name": "ObjectValidateError", "message": ...} Validation error

Update Host

PUT /api/host/:host

Update an existing host configuration.

Parameters: Same as Create Host (all optional)

curl -H "Content-Type: application/json" \
  -H "auth-token: your-token-here" \
  -X PUT \
  -d '{"ip": "192.168.1.20", "targetPort": 9000}' \
  https://proxy-host.com/api/host/example.com

Responses:

200 {"message": "\"example.com\" updated.", ...}
404 {"name": "HostNotFound", "message": "Host does not exists"}
422 Validation error

Delete Host

DELETE /api/host/:host

Remove a host configuration.

curl -H "auth-token: your-token-here" \
  -X DELETE \
  https://proxy-host.com/api/host/example.com

Responses:

200 {"message": "example.com deleted", ...}
404 {"name": "HostNotFound", "message": "Host does not exists"}

Renew Wildcard Certificate

PUT /api/host/:host/renew

Manually trigger wildcard certificate renewal.

curl -H "auth-token: your-token-here" \
  -X PUT \
  https://proxy-host.com/api/host/*.example.com/renew

Responses:

200 {"message": "Requesting wildcard cert for *.example.com"}
404 Host not found

DNS Providers

Manage DNS provider integrations for wildcard SSL certificates.

List DNS Providers

GET /api/dns

Get list of configured DNS providers.

curl -H "auth-token: your-token-here" \
  https://proxy-host.com/api/dns

Query Parameters:

detail - Include full provider details (optional)

Responses:

200 {"results": ["provider-id-1", "provider-id-2"]}

List Available Provider Types

OPTIONS /api/dns

Get list of supported DNS provider types and their configuration requirements.

curl -H "auth-token: your-token-here" \
  -X OPTIONS \
  https://proxy-host.com/api/dns

Responses:

200 {"results": [{"name": "CloudFlare", "fields": {...}}, {"name": "DigitalOcean", ...}, ...]}

Create DNS Provider

POST /api/dns

Configure a new DNS provider.

CloudFlare:

curl -H "Content-Type: application/json" \
  -H "auth-token: your-token-here" \
  -X POST \
  -d '{"name": "My CloudFlare", "dnsProvider": "Cloudflare", "token": "your-api-token"}' \
  https://proxy-host.com/api/dns

DigitalOcean:

curl -H "Content-Type: application/json" \
  -H "auth-token: your-token-here" \
  -X POST \
  -d '{"name": "My DO", "dnsProvider": "DigitalOcean", "token": "your-api-token"}' \
  https://proxy-host.com/api/dns

PorkBun:

curl -H "Content-Type: application/json" \
  -H "auth-token: your-token-here" \
  -X POST \
  -d '{"name": "My PorkBun", "dnsProvider": "PorkBun", "apiKey": "pk_xxx", "secretApiKey": "sk_xxx"}' \
  https://proxy-host.com/api/dns

Responses:

200 {"message": "\"provider-id\" added.", ...}
422 Validation error or invalid API credentials

Get DNS Provider

GET /api/dns/:id

Get a specific DNS provider configuration.

curl -H "auth-token: your-token-here" \
  https://proxy-host.com/api/dns/provider-id

Responses:

200 {"item": "provider-id", "results": {...}}
404 Provider not found

Update DNS Provider

PUT /api/dns/:id

Update DNS provider configuration.

curl -H "Content-Type: application/json" \
  -H "auth-token: your-token-here" \
  -X PUT \
  -d '{"name": "Updated Name"}' \
  https://proxy-host.com/api/dns/provider-id

Responses:

200 {"message": "\"provider-id\" updated.", ...}
404 Provider not found

Delete DNS Provider

DELETE /api/dns/:id

Remove a DNS provider and all associated domains.

curl -H "auth-token: your-token-here" \
  -X DELETE \
  https://proxy-host.com/api/dns/provider-id

Responses:

200 {"message": "provider-id deleted", ...}
404 Provider not found

List Domains

GET /api/dns/domain

List all domains from all configured providers.

curl -H "auth-token: your-token-here" \
  https://proxy-host.com/api/dns/domain

Query Parameters:

detail - Include full domain details (optional)

Responses:

200 {"results": ["example.com", "test.com"]}

Get Domain

GET /api/dns/domain/:domain

Get details for a specific domain.

curl -H "auth-token: your-token-here" \
  https://proxy-host.com/api/dns/domain/example.com

Responses:

200 {"results": [{"domain": "example.com", "zoneId": "...", ...}]}
404 Domain not found

Refresh Domains

POST /api/dns/domain/refresh/:providerId

Refresh the domain list from a DNS provider’s API.

curl -H "auth-token: your-token-here" \
  -X POST \
  https://proxy-host.com/api/dns/domain/refresh/provider-id

Responses:

200 {"results": ...} Updated domain list
404 Provider not found

Certificates

Retrieve SSL certificate information.

Get Certificate

GET /api/cert/:host

Get the SSL certificate for a host.

curl -H "auth-token: your-token-here" \
  https://proxy-host.com/api/cert/example.com

Responses:

200 Certificate data including cert_pem, fullchain_pem, privkey_pem, expiry information
404 Certificate not found

Error Responses

All endpoints may return the following error responses:

401 {"name": "LoginFailed", "message": "Invalid Credentials, login failed."} - Authentication required or invalid
404 {"name": "NotFound", "message": "..."} - Resource not found
422 {"name": "ObjectValidateError", "message": [...], "keys": [...]} - Validation errors
500 Internal server error

Notes

All timestamps are in milliseconds since epoch
The auth-token header is required for all authenticated endpoints
Host names support wildcards: * (single level) and ** (multi-level)
DNS providers are validated on creation - invalid API credentials will be rejected
Wildcard certificates are automatically renewed 30 days before expiration

API Reference

A reverse proxy and HTTPS termination service using OpenResty/nginx with a management API and web GUI

API Documentation

Authentication

Logout

Users

List Users

Get Current User

Create User

Delete User

Change Password (Self)

Change Password (Other User)

Create Invite Token

Add SSH Key

Hosts

List Hosts

Get Host

Lookup Host

Get Lookup Tree

Create Host

Update Host

Delete Host

Renew Wildcard Certificate

DNS Providers

List DNS Providers

List Available Provider Types

Create DNS Provider

Get DNS Provider

Update DNS Provider

Delete DNS Provider

List Domains

Get Domain

Refresh Domains

Certificates

Get Certificate

Error Responses

Notes

API Documentation

Authentication

Login

Logout

Users

List Users

Get Current User

Create User

Delete User

Change Password (Self)

Change Password (Other User)

Create Invite Token

Add SSH Key

Hosts

List Hosts

Get Host

Lookup Host

Get Lookup Tree

Create Host

Update Host

Delete Host

Renew Wildcard Certificate

DNS Providers

List DNS Providers

List Available Provider Types

Create DNS Provider

Get DNS Provider

Update DNS Provider

Delete DNS Provider

List Domains

Get Domain

Refresh Domains

Certificates

Get Certificate

Error Responses

Notes