# 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](https://docs.diagrid.io/develop/agents/enterprise-identity).

[Bring-your-own-cloud (BYOC)](https://docs.diagrid.io/references/glossary#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](https://docs.diagrid.io/operate/project-operations/idp-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](#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:

```bash
# 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](https://docs.diagrid.io/operate/project-operations/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:

```bash
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](https://docs.diagrid.io/references/catalyst/catalyst-cli-intro).
- **In the [Catalyst console](https://catalyst.diagrid.io)**, 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](https://docs.diagrid.io/operate/project-operations/idp-federation) — the operator-side setup that determines which identity providers a token can come from.
- [Troubleshooting](https://docs.diagrid.io/develop/agents/enterprise-identity/troubleshooting) — resolve `invalid_grant` and other rejection codes.