Authentication

Callers authenticate to services — not to agents directly. You configure authentication per service and issue credentials or service keys that are allowed to call specific service IDs.

Authentication modes (per service)

When creating or editing a service, choose one or both:

Mode	Caller behavior
JWT	Obtain a short-lived bearer token, send X-Xg3-Authorization: Bearer … on each ingress request
Service key	Send X-Xg3-Service-Key: xg3_sk_… on each ingress request

If both modes are enabled, the caller must use exactly one per request. Sending both gateway auth headers with non-empty values is rejected.

The standard HTTP Authorization header is forwarded to your backend unchanged; it is not used for xgress3 gateway authentication.

Credentials (JWT path)

Open Authentication → Credentials.

Create a credential

1. Click create and note the client ID and client secret.
2. The client secret is shown once — store it securely.
3. Add allowed services — only listed service IDs may receive tokens minted with this credential.

How callers use it

Callers POST to the regional token endpoint:

POST https://{region}.xg3.io/oauth/token

with client_id, client_secret, and scope containing account:{account_id} and service:{service_id}.

Then they call your tenant hostname with X-Xg3-Authorization: Bearer {access_token}.

Full cURL examples: Ingress authentication.

Manage credentials

You can enable/disable credentials and update allowed services. Rotating a secret typically means creating a new credential and retiring the old one.

Service keys

Open Authentication → Service Keys.

Create a service key

1. Click create and copy the full key string immediately.
2. Format: xg3_sk_{keyId}.{secret}
3. The plaintext key is shown once.
4. Add allowed services — the key may only call listed service IDs.

How callers use it

Every ingress request includes:

X-Xg3-Service-Key: xg3_sk_KEYID.SECRET

There is no token endpoint for service keys.

Allowlists

Both credentials and service keys use an allowlist of service IDs:

• A credential can mint tokens only for services on its list.
• A service key can call ingress only for services on its list.
• The account must match; keys and credentials do not grant cross-account access.

When adding a new service, update the relevant credentials or keys to include its service ID.

Choosing JWT vs service key

Aspect	JWT (credential)	Service key
Typical use	Machine clients that can call a token endpoint and cache tokens	Simple integrations, scripts, static configuration
Secret on the wire	Short-lived token; client secret only at token endpoint	Long-lived material in a header every request
Console setup	Credential + allowlisted services	Service key + allowlisted services
Rotation	Issue new credential; update clients	Create new key; disable old key

You can assign different credentials or keys to different clients for the same service, or use different auth modes on different services behind one agent.

After setup

Test with cURL using Ingress authentication, then use Request Lookup with the returned X-Xg3-Request-Id if anything fails.