Quickstart

This walkthrough takes you from zero to a successful authenticated HTTP call through xgress3. You need access to the operator console, a host where you can run the xg3 Agent, and a reachable backend URL (HTTP or HTTPS) on your private network.

Replace placeholders with your values:

Placeholder	Example
REGION	au
ACCOUNT_ID	acme
SERVICE_ID	api
BACKEND_URL	https://pos-server.workplace.local/

1. Create an account

1. Sign in to the xgress3 console with your organisation identity provider.
2. If you are not yet in an account, open Get started and Create an account.
3. Choose an account ID (3–15 characters, lowercase letters and digits only, for example acme).
4. Select your region in the header (for example au).

See Getting started for joining an existing account instead.

2. Run the agent

On a machine in your network that can reach your backend and the public internet:

1. Install the xg3 Agent release binary on that host.
2. Start it with your region (default gateway URL is https://{region}.xg3.io unless you set XG3_GATEWAY):

xg3agent --region REGION

3. The agent prints an enrollment code in XXXX-XXXX form (for example 3679-CDEF). Copy it.

Details: Install and run, Enrollment.

3. Approve enrollment in the console

1. In the console, open Agents.
2. Click Enroll Agent.
3. Enter the code from the agent output and click Approve.
4. You are taken to the agent detail page. Wait until the agent shows as connected (tunnel up).

4. Create a service

1. On the agent detail page, click Add Service (or use Services after enrollment).
2. Enter your Backend Base URL (absolute http:// or https:// URI, for example https://pos-server.workplace.local/).
3. Confirm or edit the Service ID (used in the public hostname).
4. Choose authentication modes (JWT, service key, or both).
5. Save the service.

Your public ingress hostname will be:

https://ACCOUNT_ID--SERVICE_ID.REGION.xg3.io

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

5. Create caller credentials

Choose one mode matching your service configuration.

Option A — JWT credential

1. Open Authentication → Credentials.
2. Create a credential and note the client ID and client secret (secret shown once).
3. Add SERVICE_ID to the credential’s allowed services list.

Option B — Service key

1. Open Authentication → Service Keys.
2. Create a key and copy the full value (xg3_sk_…) — it is shown once.
3. Add SERVICE_ID to the key’s allowed services list.

See Authentication for choosing between JWT and service keys.

6. Call your service

JWT example

Obtain a token from the regional platform host:

ACCESS_TOKEN=$(curl -sS -X POST "https://REGION.xg3.io/oauth/token" \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "CLIENT_ID",
    "client_secret": "CLIENT_SECRET",
    "scope": "account:ACCOUNT_ID service:SERVICE_ID"
  }' | jq -r .access_token)

Call your backend through the tenant hostname:

curl -sS -D - "https://ACCOUNT_ID--SERVICE_ID.REGION.xg3.io/v1/health" \
  -H "X-Xg3-Authorization: Bearer ${ACCESS_TOKEN}"

Service key example

curl -sS -D - "https://ACCOUNT_ID--SERVICE_ID.REGION.xg3.io/v1/health" \
  -H "X-Xg3-Service-Key: xg3_sk_KEYID.SECRET"

Check the response headers for X-Xg3-Request-Id. You can look up that ID under Request Lookup in the console if something fails.

Full reference: Ingress authentication.

Checklist

Step	Done when
Account created	You see the dashboard for your account
Agent running	Enrollment code approved; agent shows connected
Service created	Public hostname matches account--service.region.xg3.io
Credential or key	Allowlist includes your service ID
HTTP call succeeds	Backend response returned; X-Xg3-Request-Id present

Common blockers

Symptom	What to check
Enrollment code rejected	Code expired — use the latest code from the agent; region matches header
Ingress returns agent unavailable	Agent not connected; check agent logs and firewall (outbound HTTPS to gateway)
401 / policy deny on ingress	Wrong auth header, credential not allowlisted for service, or service auth mode mismatch
Backend errors	Backend URL reachable from the agent host; path is correct

See Troubleshooting for more detail.