Tunnel API

AuthenticationCopy Anchor Link

Management endpoints use your authenticated dashboard session. Requests that change configuration require the dashboard's exact Origin header. You can manage only connectors and websites in the selected account.

Replace ACCOUNT-ID, SITE-ID, and TUNNEL-ID in the paths below. Read the current configuration revision before changing it. An initial configuration uses an empty revision; a stale revision returns HTTP 409.

Account connector endpointsCopy Anchor Link

Use GET or PUT /customer/api/account-tunnels/ACCOUNT-ID?account=ACCOUNT-ID.

GET returns config, connection reports, control_url, account_id, websites, publications, and any migration notice. It also includes service_reports and desired service_revisions keyed by connector ID. Secrets are redacted; token_configured indicates whether the connector has a credential.

PUT accepts the connector list and current revision:

{
  "revision": "CURRENT-REVISION",
  "connectors": [{
    "id": "customer-server",
    "name": "Customer server",
    "enabled": true,
    "auto_update_disabled": false
  }],
  "routes": []
}

Set auto_update_disabled to true to opt out of automatic updates. This does not change the token.

Removing a connector referenced by a website returns HTTP 400. Disable it to stop its services while keeping the routes configured.

Website route endpointsCopy Anchor Link

Use GET or PUT /customer/api/tunnels/SITE-ID?account=ACCOUNT-ID.

GET includes the account's connectors for route selection. PUT accepts revision, an empty connectors array, and website routes. Each route specifies id, tunnel_id, service, path, match, and enabled.

Routes can reference only connectors in the website's account. General website edits preserve these routes. For a whole website, set its origin to tunnel://CONNECTOR-ID/SERVICE through the website configuration endpoint.

Token endpointCopy Anchor Link

Send POST /customer/api/account-tunnels/ACCOUNT-ID/TUNNEL-ID/token?account=ACCOUNT-ID with:

{"revision":"CURRENT-REVISION"}

The response contains a new token and updated redacted config. Save the token securely: it is returned only once. Replacing it immediately prevents the old token from fetching configuration and disconnects existing replicas shortly afterward.

Activation codesCopy Anchor Link

Send POST /customer/api/account-tunnels/ACCOUNT-ID/TUNNEL-ID/activation?account=ACCOUNT-ID with the current revision.

The response contains code, expires, and updated config. A code expires after ten minutes and can be used once. Creating one leaves the running token unchanged; generating another invalidates the previous unused code.

The connector redeems it at POST /api/agent/connectors/activate with account_id, tunnel_id, and code. This endpoint authenticates with the code rather than dashboard cookies.

Successful redemption replaces the permanent token and returns account_id, tunnel_id, and token. Invalid, expired, or already-used codes return HTTP 401. Temporary storage failures return HTTP 503.

Token replacement or revocation also cancels an outstanding activation code. Credential responses use Cache-Control: no-store.

Connector discoveryCopy Anchor Link

Connectors fetch configuration from GET /api/agent/connectors/config with:

Authorization: Bearer TUNNEL-TOKEN
X-Loclix-Account: ACCOUNT-ID
X-Loclix-Tunnel: TUNNEL-ID
X-Loclix-Connector-Protocol: 3

The response includes account_id, tunnel_id, endpoints, and auto_update_disabled. Each current endpoint supplies address, server_name, account_scoped: true, and a PEM trust bundle for certificate verification.

The shared address is waf-ingress.loclix.network:443. Discovery can return it before a website is published. Invalid credentials return HTTP 401; an empty endpoint list means no connection endpoint is currently available.

DownloadsCopy Anchor Link

Use the installation command from Install connector. Downloads are served from your dashboard host under /downloads/connectors/.

The installer supports Linux amd64 and arm64 with systemd 247 or later. Architecture directories linux-amd64 and linux-arm64 contain loclix-connector, its .sha256 checksum, signed release.json metadata, and THIRD-PARTY-NOTICES.txt.

Retain the license notices when redistributing a connector binary. See Connector updates for update controls.

Managed service definitionsCopy Anchor Link

In an account connector, set services_managed: true and supply a complete services map:

{
  "id": "customer-server",
  "name": "Customer server",
  "enabled": true,
  "services_managed": true,
  "services": {
    "web": "http://127.0.0.1:8080",
    "api": "http://127.0.0.1:3000"
  }
}

Include this connector object in the account configuration's connectors array, alongside the current revision. The map replaces the service definitions for every replica. Saving it can interrupt active connections while the connector applies the change.

Maps support up to 64 services and 32 KiB of definitions. Removing a service still referenced by a website returns HTTP 400. An empty map is allowed when no publications reference its services.

Use service_reports to inspect applied destinations. A desired address is not active until the connector reports it. Reports expire after 60 seconds, and older connectors cannot apply dashboard-managed maps. See Local services for version requirements and pending changes.