Identity and network trust
Updated on 3 November 2026.
Identify the user behind every gateway call, require identity or a conversation ID where you need it, verify caller JWTs, and limit which networks may call the gateway.
Configure this control
Choose the mode used by your gateway. When the Policy Engine is on, published rules govern this control; classic values saved through Edit anyway apply only after the engine is disabled. See What happens to classic settings.
- Classic settings
- Policy Engine
Turn it on for an app
Identity is configured per app. Open the app from Settings > AI Gateway > LLM Gateway and choose any Configure option to open the app workspace's Settings tab, then select Identity Aware under Identity & content. Apps with it on show an Identity aware chip in the app list.
New apps have every control off: identity optional, conversation ID optional, any user domain, JWT not verified. Network limits are set separately under Source IP restrictions in the Guardrails tab.
Going further with the Policy Engine
Open Govern > Policy Engine > LLM Gateway > Controls > Identity & Network Trust. This control sets who must prove identity, who must send a conversation ID, and which networks may call. When the engine is on for the LLM Gateway, the app's identity requirements freeze and published rules apply instead (see What happens to classic settings). Identity sources, including JWT signing keys, stay in app settings. Identity capture can override how a matching request supplies identity; where no capture rule sets a value, the app setting remains the fallback.
Use a recipe or the add menu in Require identity, Require conversation ID, Allowed source IPs, or Identity capture. Set the scope and outcome, then Save to draft. The requirement controls include:
Scenarios the card supports:
- Require identity tenant-wide, waive it for one service app. Scope Required to Everyone and Not required to one Application or App tag. The highest-priority match wins; Required wins equal-priority ties.
- Production only. Require identity and a conversation ID, and limit source ranges, when request metadata marks the environment as production.
- Per-group network limits. Scope by People, Smart group, API surface, Environment, Tool or Source network. Requested model and Provider are not offered.
runs on requestpriority 850
Source IP ranges ignore priority: every matching configuration narrows the list, and ranges that do not overlap are dropped. Two configurations with disjoint ranges (for example one app's office range and a tenant-wide VPN range) leave no allowed address, so the matching traffic is blocked.
Identity capture
Use Identity capture for caller-reading settings that differ by application, person or group. The section shows how each setting combines:
Without a capture override, each app's identity settings decide how its caller is read, and conversation IDs use the built-in headers. Requiring identity is a separate decision from how identity is captured.
Start from a recipe or a section's add menu, choose who it applies to, then Save to draft. Review the section's How rules combine explanation and test a matching caller and an exception before publishing.
How it works
- Request Arrives - App sends an API call with identity info
- Gateway Identifies User - Extracts identity via header or JWT token
- Per-User Tracking - Logs, findings and usage are attributed to the user
Authentication modes
Header based (trusted clients)
Uses the X-User-Email header to identify users. If your app handles user login and makes LLM calls from your own backend, this is the easiest and recommended approach - just pass the logged-in user's email as a header.
X-User-Email: user@company.com
JWT with a JWKS URL (untrusted clients)
Turn on JWT authentication and set Signing key source to JWKS URL. The gateway validates caller JWTs against the keys at that URL, which supports key rotation. Ideal for production OAuth/OIDC flows with providers like Auth0, Okta, or Google.
https://your-provider/.well-known/jwks.json
JWT with a public key (PEM)
Set Signing key source to Public key PEM to validate JWTs with a static RSA public key. Suitable for environments with fixed signing keys where JWKS isn't available.
-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqh...
-----END PUBLIC KEY-----
JWT claims validation
Access controls
Each app has three independent identity controls, plus Enforce conversation ID. They compose: turn on header identity to accept the X-User-Email header, turn on enforced identity to make identity mandatory, and list allowed domains to whitelist who counts as identity.
Identity header mode
Controls whether the gateway reads the X-User-Email header at all.
Leave it off for apps using JWT only. Turn it on for trusted backends that pass the logged-in user's email to the gateway.
Enforce identity
Makes identity mandatory. After auth succeeds, the request is only accepted if identity was also provided.
JWT auth always satisfies Enforce Identity - the JWT itself is the identity. The X-User-Email header only satisfies it when Identity Header Mode is also enabled.
Allowed user domains
A list of email domains permitted as identity.
The check runs on both the X-User-Email header and the email claim extracted from JWTs. Requests from disallowed domains are rejected even if the JWT signature is otherwise valid.
To accept calls only from known IP ranges, use Source IP restrictions.
Pair X-User-Email with X-Conversation-Id to view per-user activity grouped into individual conversations in the dashboard.
Related
- Conversation grouping - the
X-Conversation-Idheader. - Security guardrails - per-app source IP restrictions.
- Policy Engine overview