Call models with enterprise identity

A business system (for example an in-bank office, customer-service, or approval system) can skip applying for an API key and instead call models carrying a token the enterprise identity source (OIDC) issued for the current user. The gateway finishes token verification and authorization locally. Every call is recorded under a specific person and department. Department quotas and personal quotas still apply.

1. How it works

1. The business system obtains a JWT (ID Token, or a JWT-format Access Token) from the enterprise identity source for the current user. The token's audience (aud) is the business system's own client ID.
2. The business system calls the gateway directly and carries that token in the Authorization header. The call URL and body are identical to using an API key.
3. The gateway verifies the token with the identity-source signing public key stored locally, finds the matching platform user by sub in the token, then judges whether that user can use the requested model in the workspace this call belongs to.
4. After the token expires, the business system fetches a new one from the identity source. The whole process does not need any admin-console API.

Everything the gateway needs to verify the token (issuer, audience allowlist, person-to-workspace relations, signing public keys) is stored locally on the gateway node. Signing public keys are fetched by the gateway directly from the identity source and stored locally, so even if the control plane is unavailable for a long time, calls by existing users are not affected; see section 6.

2. Prerequisites

Completed by a unit administrator in the admin console (detailed steps are in the Identity sources and sign-in security topic):

1. Connect an OIDC identity source: on the Single sign-on page choose IAM, type OpenID Connect, fill in the identity-source address (Issuer), client ID, and client secret, save, and finish a test sign-in.
2. Enable business-system calls: in the Business-system calls block on the same page, turn on Allow business systems to call models with an identity-source token, and fill in Business-system client IDs (at least one). The audience of the user token the business system obtains must be one of the IDs registered here.
3. The person already exists on the platform: the caller must be an enabled user of this unit, and already associated with that identity source — the user has signed in once through that identity source, or association was completed when directory sync pushed them. A disabled user cannot call.
4. Workspace and model available: the caller belongs to at least one workspace, and the model group that holds the requested model has been distributed to that user or that workspace.

On save, the platform immediately reads the signing public key once from the identity source and checks that the identity-source address is reachable. If the read fails, save does not succeed and the page shows the reason.

Notes:

• Only a unit OIDC identity source can enable business-system calls. OAuth2 (generic) identity sources and platform-level identity sources do not provide this.
• The same issuer can be used for business-system calls by only one unit. When another unit already uses it, save fails with "this identity source is already used by another unit for business-system calls".
• The gateway only accepts tokens signed with these asymmetric algorithms: RS256, RS384, RS512, PS256, ES256, ES384, EdDSA. Tokens using HS256 or similar symmetric algorithms, or unsigned tokens, are rejected.

3. Call URL

After the identity-source configuration is saved, the page shows Business-system call URL, which is this platform's public access URL. Model-call APIs sit under /api/v1/agent-gateway/ on that URL, the same as when using an API key:

The token may sit in Authorization: Bearer, x-api-key, or x-goog-api-key per each protocol's habit. The gateway recognizes it as an enterprise-identity token by the token format.

4. Request example

curl https://zenova.example.com/api/v1/agent-gateway/openai/v1/chat/completions \
  -H "Authorization: Bearer $IDP_ID_TOKEN" \
  -H "X-Zenova-Workspace: 4f1c2b7e-9a3d-4c55-8e0f-2a6b1d9c7e31" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "your-gateway-model",
    "messages": [{"role": "user", "content": "Summarize the key points of this expense claim."}]
  }'

• Authorization: the token the identity source issued for the current user.
• X-Zenova-Workspace: the workspace ID (UUID) this call belongs to.
• model: an available model name. Call the model-list API first to see models available to the current user in that workspace.

4.1 Specify a workspace

Every enterprise-identity call must belong to a specific workspace:

A tenant administrator calling with an enterprise-identity token must also specify a workspace. Business systems should always carry this header.

4.2 Token requirements

After the identity source rotates signing public keys, when the gateway sees a new kid it fetches the latest keys directly from the identity source (at most once per 60 seconds per node).

5. Metering, quotas, and call records

• Caller in the call record shows as Business system (identity-source token), with the person and their department.
• Usage is rolled up by caller, department, function group, and workspace, and can be viewed by department on the usage and cost page.
• Department quotas, function-group quotas, and personal quotas apply the same as when that user uses the platform directly. When a quota is exceeded, the call is rejected per the quota settings.
• Routing rules, guardrails, and traffic protection apply to enterprise-identity calls as usual.

6. Behavior when the control plane is unavailable

7. Troubleshooting errors

Errors are returned in the error format of the protocol used (OpenAI, Anthropic, Gemini). The error code is in the code field of the error object.

An administrator can filter enterprise-identity calls in call records by person, and confirm caller, model, status, and duration.