Skip to content

Aegis Gateway API

The Aegis Gateway management API lets you automate tasks that you can also do through the dashboard, such as managing SSH access keys, requesting certificates, and checking gateway diagnostics.

[!TIP] All API examples below use admin as the username. Replace it with your actual admin username, and replace replace-with-strong-password with your actual password.

Authentication

Every API request must include HTTP Basic Authentication. Use your admin username and password.

The examples below use curl with the -u username:password option. For security, you may want to pass the password through an environment variable or a secrets manager instead of typing it directly into commands.

SSH Access Keys

These endpoints manage the public keys allowed to open reverse tunnels through the gateway account.

List SSH Keys

curl -sku admin:'replace-with-strong-password' \
  https://your-server-address:8443/api/ssh-keys

Add an SSH Key

curl -sku admin:'replace-with-strong-password' \
  -X POST https://your-server-address:8443/api/ssh-keys \
  -H 'Content-Type: application/json' \
  -d '{"publicKey":"ssh-ed25519 AAAAC3Nza... user@host"}'

Replace the example key with your own public key. It usually starts with ssh-ed25519, ssh-rsa, or ecdsa-sha2-nistp256.

Delete an SSH Key

curl -sku admin:'replace-with-strong-password' \
  -X DELETE https://your-server-address:8443/api/ssh-keys/<key-id>

Replace <key-id> with the identifier returned when you listed or added the key.

Management Certificate

These endpoints control the certificate used by the management interface on port 8443.

Request a Certificate

curl -sku admin:'replace-with-strong-password' \
  -X POST https://your-server-address:8443/api/management-certificate/request

The gateway will request a certificate from Let's Encrypt for the domain you are currently using. After a successful request, the application restarts automatically to load the new certificate.

[!NOTE] Make sure LETSENCRYPT_EMAIL is set and you are accessing the dashboard using a public domain name before requesting a certificate.

Services

These endpoints manage the services published through Aegis Gateway.

List Services

curl -sku admin:'replace-with-strong-password' \
  https://your-server-address:8443/api/services

Create a Service

curl -sku admin:'replace-with-strong-password' \
  -X POST https://your-server-address:8443/api/services \
  -H 'Content-Type: application/json' \
  -d '{
    "publicHostname": "www.example.com",
    "backendAddress": "192.168.1.50",
    "backendPort": 8080,
    "backendProtocol": "HTTP"
  }'

The fields are:

  • publicHostname — the domain name visitors will use.
  • backendAddress — the IP address or hostname where the service is running.
  • backendPort — the port the service is listening on.
  • backendProtocol — how to connect to the back-end. Use one of:
  • HTTP — plain HTTP.
  • HTTPS_VERIFIED — HTTPS with a verified certificate.
  • HTTPS_UNVERIFIED — HTTPS with a self-signed or unverified certificate.

Toggle a Service On or Off

curl -sku admin:'replace-with-strong-password' \
  -X PATCH https://your-server-address:8443/api/services/<id>/status

This switches the service between enabled and disabled.

Delete a Service

curl -sku admin:'replace-with-strong-password' \
  -X DELETE https://your-server-address:8443/api/services/<id>

Diagnostics

HAProxy Diagnostics

curl -sku admin:'replace-with-strong-password' \
  https://your-server-address:8443/api/diagnostics/haproxy

This returns the current state of the HAProxy configuration, including:

  • lastResult — the result of the last reconcile pass (never-run, unchanged, changed-reload-skipped, changed-reloaded, or failed).
  • lastError — any error message from the last reconcile pass.
  • lastReconcileAt, lastConfigChangeAt, lastReloadAt — timestamps of recent activity.
  • reloadEnabled, periodicReconcileEnabled, reconcileInProgress — flags showing whether reloads and reconcile are active.

Use this endpoint when you want to confirm that recent service changes have been applied.

Common Options

  • Replace your-server-address with the domain name or IP address of your gateway.
  • Use port 8443 for all management API calls.
  • Use -k or --insecure with curl only if the management interface still uses a self-signed certificate. Remove it once a trusted certificate is installed.