Overview

xgress3 is a zero-trust HTTP access layer. Authorized clients call a public regional hostname; xgress3 validates each request and relays it through an outbound-only agent running in your network to your private HTTP or HTTPS backend.

xgress3 is not a VPN, port forwarder, or general network tunnel. Only explicitly configured HTTP services receive traffic.

How it fits together

1. A client sends HTTPS to your service hostname (for example https://acme--api.au.xg3.io/orders).
2. The regional gateway authenticates the caller and checks that the service is enabled.
3. The agent receives the relayed request over a persistent outbound tunnel and forwards it to your backend URL.
4. The response returns along the same path. Every response includes X-Xg3-Request-Id for tracing — see Request logging for what xgress3 stores.

How the agent-to-gateway connection is secured

The agent never accepts inbound connections — it always initiates outbound to the regional gateway, and the connection is protected in two layers:

• Outbound TLS — the agent opens a standard outbound HTTPS/TLS connection to the regional gateway hostname (for example https://au.xg3.io). Nothing needs to be opened on your firewall or the agent host; only outbound HTTPS (port 443) must be allowed.
• Mutual TLS once enrolled — after enrollment completes, the agent holds an xgress3-issued client certificate and presents it when opening the tunnel, so the gateway authenticates the agent (mTLS) in addition to the agent authenticating the gateway via its server certificate. The agent renews this certificate automatically before it expires — see Agent operations — certificate renewal.

This certificate secures the agent-to-gateway tunnel only. It is separate from caller authentication (JWT or service key) enforced on ingress requests — see Authentication modes below.

Regions

xgress3 runs on Microsoft Azure. Traffic stays in the region you choose when enrolling an agent (for example au → au.xg3.io). Agents are bound to one region for their lifetime. Services inherit the region of the agent they use.

Available regions and Azure data centres are listed in Cloud and regions.

Identifiers

Identifier	Rules	Example
Account ID	3–15 characters; lowercase letters a–z and digits 0–9 only	acme
Service ID	Chosen when you create a service; appears in the public hostname after --	api

Public service URL shape:

https://{account_id}--{service_id}.{region}.xg3.io/{path}?{query}

Example: https://acme--api.au.xg3.io/v1/health

The full path and query string are forwarded to your backend unchanged.

Four core objects

Object	What it is
Agent	Software you run in your network. After enrollment it maintains an outbound tunnel and forwards HTTP to your backends.
Service	A named ingress front door: public hostname, backend URL, and authentication settings. Each service uses exactly one agent.
Credential	OAuth-style client ID and secret. Callers exchange these for short-lived JWT access tokens (when the service allows JWT).
Service key	A long-lived secret sent on each request (when the service allows service keys). Shown once when created.

Credentials and service keys include an allowlist of service IDs they may be used with. The service record ties caller authorization to the correct agent and backend.

Authentication modes

Each service allows one or both of:

• JWT — callers obtain a bearer token from POST https://{region}.xg3.io/oauth/token, then send X-Xg3-Authorization: Bearer … on ingress.
• Service key — callers send X-Xg3-Service-Key: xg3_sk_… on every ingress request.

Do not send both gateway auth headers on the same request when both are non-empty; that combination is rejected.

The standard Authorization header is not used for gateway authentication. If your backend expects Authorization, it is forwarded unchanged.

Typical roles

Role	Start here
Console operator	Console introduction → Getting started
Billing admin	Billing and subscriptions
Agent administrator	Agent introduction → Install and run
API integrator	Ingress authentication

For a full first-time setup walkthrough, see Quickstart. For throughput, parallel downloads, and operator-tunable limits, see Transport and limits.