API Endpoints

The Go control plane serves two categories of routes: admin API routes at /v1/admin/* for management operations, and client/device routes at /v1/* for enrollment, policy, trust, and gateway operations.

The admin web interface is served at /admin/* with HTML pages.

Note: Request and response schemas shown below are representative. Consult the control plane source code for exact field names and types.

Health Check

GET /healthz

Unauthenticated liveness probe.

Response (200):

{"status": "ok"}

GET /readyz

Unauthenticated readiness probe (verifies database connectivity).

Response (200):

{"status": "ready"}

Admin API: User Management

/v1/admin/users

• GET: List all users for the authenticated tenant
• POST (via /v1/admin/users/lifecycle): Create, update, or delete users

/v1/admin/users/lifecycle

Mutating user operations (create, suspend, reactivate, delete) are handled through the lifecycle endpoint.

/v1/admin/users/password

Set or reset a user's password.

/v1/admin/users/suspend

Suspend a user account. Terminates all active sessions.

/v1/admin/users/reactivate

Reactivate a suspended user account.

/v1/admin/users/totp/enroll

Start TOTP MFA enrollment for a user. Returns a provisioning URI for authenticator apps.

/v1/admin/users/totp/verify

Verify a TOTP code to complete MFA enrollment.

/v1/admin/users/totp/disable

Disable MFA for a user (admin action, audit-logged).

Admin API: Group Management

/v1/admin/groups

• GET: List groups
• POST (via /v1/admin/groups/lifecycle): Create, update, or delete groups

Admin API: Device Management

/v1/admin/devices

• GET: List enrolled devices with filtering

/v1/admin/devices/lifecycle

Mutating device operations (suspend, revoke).

POST /v1/admin/devices/batch

Batch operations on multiple devices (e.g., bulk revoke).

Admin API: RBAC

POST /v1/admin/rbac/grant

Grant a role to a user.

POST /v1/admin/rbac/revoke

Revoke a role from a user.

Admin API: Sessions

/v1/admin/sessions

List active VPN sessions with device, user, gateway, and connection metadata.

Admin API: Enrollment Tokens

POST /v1/admin/tokens/generate

Generate an enrollment token for device enrollment.

GET /v1/admin/tokens

List tokens with filtering by status and tenant.

GET /v1/admin/tokens/{token_id}

Get details of a specific token.

POST /v1/admin/tokens/{token_id}/revoke

Revoke a token. Revoked tokens cannot be used for enrollment.

Admin API: Policy

POST /v1/admin/policy/publish

Publish a policy bundle to the specified channel (canary or stable).

Admin API: Settings

/v1/admin/settings/providers

Manage identity provider configurations (OIDC, SAML, Keycloak, Azure Entra ID, Okta).

/v1/admin/settings/signers

Manage signing key configurations.

/v1/admin/settings/gateway-pools

Manage gateway pool configurations.

Admin API: Tenants and Entitlements

GET /v1/admin/tenants

List tenants.

POST /v1/admin/tenants/lifecycle

Mutating tenant operations.

GET /v1/admin/tenants/{tenant_id}/entitlement

Get resolved entitlement for a tenant.

GET /v1/admin/tenants/{tenant_id}/entitlement/status

Get entitlement enforcement status.

GET /v1/admin/tenants/{tenant_id}/alerts

Get entitlement alerts (approaching limits, overages).

GET /v1/admin/tenants/{tenant_id}/usage

Get metered usage for a tenant.

Admin API: License

POST /v1/admin/license/reload

Reload the license from disk.

GET /v1/admin/license/status

Get current license status and details.

Admin API: Audit

GET /v1/admin/audit/export

Export audit logs as CSV or JSON.

GET /v1/admin/audit/connectors/schema

Get the schema for audit event connectors (SIEM integration).

Admin API: Operations

GET /v1/admin/gateway/health

Get gateway fleet health status.

GET /v1/admin/certs/expiry

Check certificate expiry dates.

/v1/admin/ops/export

Export operational data.

POST /v1/admin/workflows/run

Execute an operational workflow.

GET /v1/admin/dashboard/overview

Get dashboard overview metrics.

GET /v1/admin/compliance/retention

Get data retention policy status.

GET /v1/admin/connection_truth

Get connection truth data for monitoring.

Admin API: API Keys

POST /v1/admin/api-keys

Generate a new API key for machine-to-machine authentication.

GET /v1/admin/api-keys

List existing API keys.

Admin API: Directory Sync

POST /v1/admin/directory-sync/snapshot

Ingest a directory snapshot from an external provider.

GET /v1/admin/directory-sync/status

Get directory sync status.

POST /v1/admin/directory-sync/keycloak/run

Trigger a Keycloak directory sync.

Admin API: SIEM

/v1/admin/siem/connector

Manage SIEM connector configuration for audit event forwarding.

Admin API: Incident Response

/v1/admin/incident/playbook

Get or execute incident response playbooks.

Client / Device API

POST /v1/enroll

Enroll a new device using an enrollment token.

POST /v1/enroll/oidc

Enroll a device using OIDC authentication.

POST /v1/enroll/saml

Enroll a device using SAML authentication.

GET /v1/mobile/auth/oidc/providers

List available OIDC providers for mobile client enrollment.

Trust and Policy Routes

GET /v1/trust/anchors

Fetch the current trust anchor set.

POST /v1/trust/anchors/rotate

Rotate trust anchors (admin operation).

GET /v1/policy/bundle

Fetch the current policy bundle for the authenticated device.

GET /v1/policy/digest

Fetch the current policy digest (for lightweight change detection).

SPC (Security Policy Certificate) Routes

POST /v1/spc/issue

Issue a new SPC.

GET /v1/spc/bundle

Fetch the current SPC bundle.

POST /v1/spc/rotate

Rotate SPC keys.

POST /v1/spc/revoke

Revoke an SPC.

GET /v1/spc/validate

Validate an SPC.

Gateway Runtime Routes

GET /v1/gateway/runtime/trust-anchors

Gateway fetches its trust anchor configuration.

GET /v1/gateway/runtime/policy-bundle

Gateway fetches the current policy bundle.

GET /v1/gateway/runtime/deployment-config

Gateway fetches its deployment configuration.

GET /v1/gateway/runtime/spc-bundle

Gateway fetches the SPC bundle.

GET /v1/gateway/runtime/auth-material-manifest

Gateway fetches authentication material manifest.

GET /v1/gateway/runtime/client-admission-grant

Gateway checks client admission grants.

GET /v1/gateway/pools

Fetch gateway pool directory (used by clients for gateway selection).

Metering

/v1/gateway/metering

Gateway reports metering data (bandwidth, session counts).

Posture, Update, and Telemetry

POST /v1/posture/assertion

Submit a device posture assertion.

GET /v1/update/manifest

Fetch the update manifest (client version, available updates).

GET /v1/update/package

Download an update package.

POST /v1/audit/ingest

Ingest audit events from gateways.

GET /v1/audit/events

Query audit events.

GET /v1/audit/export/syslog

Export audit events in syslog format.

GET /v1/audit/export/webhook

Export audit events to a webhook endpoint.

POST /v1/telemetry/session

Ingest session telemetry data.

Error Response Format

All error responses follow a consistent structure:

{
  "error": "error_code",
  "detail": "Human-readable description"
}