Skip to main content

Custom identity provider tokens

On the SaaS path, diagrid login authenticates you against Diagrid's managed identity provider, and the CLI sends the resulting JWT as X-Diagrid-User-Token: Bearer on each agent invocation. This works whenever the target deployment trusts the Diagrid identity provider as an upstream — the SaaS default. For the wider flow, see the Enterprise identity overview.

Bring-your-own-cloud (BYOC) deployments often trust your own identity provider but not the Diagrid identity provider, so diagrid login produces a token Catalyst rejects. In that case you supply a token from your own identity provider directly. This is a first-class path — Catalyst verifies the token against the federation your operator configured and enforces the same policy it applies to a SaaS login.

You do this by setting the X-Diagrid-User-Token header yourself when you invoke the agent — see Entry points.

Acquire a token from your identity provider​

First, obtain a user JWT from the identity provider your Catalyst deployment trusts, using that provider's own tooling — for example:

# Auth0
auth0 login
auth0 test token --audience <your-api-audience>

# Microsoft Entra ID (Azure CLI)
az account get-access-token --resource <your-api-resource> --query accessToken -o tsv

The token's issuer (iss claim) must match a federation your operator has configured. See IdP federation for how federations are set up and which providers are supported.

Set the header yourself​

Attach the token as an X-Diagrid-User-Token header on the request that invokes the agent. This works from any caller — a script, a service, a CI job, or any client that speaks plain HTTP:

curl -X POST "https://<your-agent-endpoint>/invoke" \
  -H "X-Diagrid-User-Token: Bearer <your-jwt>" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

Catalyst verifies the token against the matching federation and propagates the user identity exactly as it would for a SaaS login — same verification, same policy.

Entry points​

Setting the header yourself is the supported path today.

  • On the CLI, there is no flag for passing a custom user JWT. The only global authentication flag is --api-key, which authenticates you to the Diagrid control plane, not the agent. See the Diagrid CLI reference.
  • In the Catalyst console, the agent chat panel has no entry point for a custom token, so use an HTTP client to test an agent under a federated identity.

What's next​

  • IdP federation — the operator-side setup that determines which identity providers a token can come from.
  • Troubleshooting — resolve oauth.invalid_issuer and other rejection codes.
Last updated on