# Enterprise identity for agents

Enterprise identity lets your agents run under the identity of the **end user** who invoked them, rather than a single shared service identity. Catalyst verifies who called the agent, hands your code a trusted user object, and propagates that identity to the downstream tools the agent calls — with no authentication code in the agent. For the underlying trust model, see [Identities](https://docs.diagrid.io/concepts/identities) and [Security](https://docs.diagrid.io/concepts/security).

This works with **any Python agent framework you serve over ASGI** — vanilla LangGraph, CrewAI, or Google ADK — because the identity plumbing lives in the Catalyst data plane and a thin ASGI middleware, not in a framework-specific runtime.

## What it gives you

- **Authenticated users.** Know which real user is behind each agent invocation, and reject calls that carry no valid identity.
- **Audit trail.** Every downstream tool call carries the originating user's identity, so an auditor can trace an action back to the person who triggered it.
- **Enforcement where it matters.** Make an individual MCP server reject any tool call that carries no verified user, so a sensitive action cannot run unattributed.

Human-in-the-loop approval is **not supported on this path** — see the [callout below](#human-in-the-loop-is-workflow-only).

## How it works

Three layers cooperate to carry a user identity from the caller all the way to a downstream tool. Two of them run inside the Catalyst data plane; the third is a small library you add to your agent.

```mermaid
flowchart TD
  USER(User)
  CLI(diagrid CLI login)
  subgraph DataPlane[Catalyst data plane]
    INBOUND(Inbound auth middleware)
    PROXY(MCP proxy - OBO minting)
  end
  AGENT(Your agent + helper library)
  MCP(Downstream MCP server)

  USER-->CLI
  CLI-- X-Diagrid-User-Token --> INBOUND
  INBOUND-- verified user token --> AGENT
  AGENT-- MCP call + user token --> PROXY
  PROXY-- delegated user JWT --> MCP
```

1. **Inbound authentication.** Catalyst intercepts the incoming request, verifies the upstream JWT the caller presented, and exchanges it for a Catalyst-issued user token. It forwards that token to your app in the `X-Diagrid-User-Token` header. Your agent never sees the raw upstream credential.
2. **`diagrid.identity` helper library.** A thin, drop-in library for vanilla frameworks. It reads `X-Diagrid-User-Token`, gives your handler a verified user object, and enforces the identity policy you configure. See [OAuth with the helper library](https://docs.diagrid.io/develop/agents/enterprise-identity/oauth-helper).
3. **MCP proxy.** When your agent calls an MCP tool on a server that [requires a user identity](https://docs.diagrid.io/develop/agents/enterprise-identity/require-user-identity), the Catalyst MCP proxy mints a delegated token carrying the user's identity and attaches it to the forwarded call. Your agent sends the caller's token using the identity-aware HTTP client; the proxy does the minting. A server with no such requirement receives no user identity — that requirement is what turns propagation on. See [On behalf of](https://docs.diagrid.io/develop/agents/enterprise-identity/on-behalf-of).

## Standards

Enterprise identity is built on open standards, so it interoperates with your existing identity provider and tooling:

- **OAuth 2.0** and **OpenID Connect (OIDC)** — user authentication and token issuance.
- **[RFC 8693](https://datatracker.ietf.org/doc/html/rfc8693)** (token exchange) — the delegation grant that mints on-behalf-of tokens.
- **[RFC 8707](https://datatracker.ietf.org/doc/html/rfc8707)** (resource indicators) — audience-scoping so a token minted for one server cannot be replayed against another.

## Human-in-the-loop is workflow-only

:::warning HITL requires the workflow path

Human-in-the-loop approval is **not available** on the sync path described here. A synchronous HTTP request cannot hold the caller's connection open indefinitely while it waits for an external approval that may take minutes or hours.

HITL needs durable workflow semantics — the ability to pause, persist state, and resume when an external event arrives. That is only available when your agent runs under the workflow-centric path. See [Workflow patterns](https://docs.diagrid.io/develop/workflows/patterns) for the external-events pattern that backs HITL today.

:::

## Next steps

- [OAuth with the helper library](https://docs.diagrid.io/develop/agents/enterprise-identity/oauth-helper) — Read the verified user in any Python ASGI agent with diagrid.identity.
- [On behalf of](https://docs.diagrid.io/develop/agents/enterprise-identity/on-behalf-of) — Propagate the user identity to downstream MCP tools and sub-agents.
- [Require a user identity](https://docs.diagrid.io/develop/agents/enterprise-identity/require-user-identity) — Make an MCP server reject tool calls that carry no verified end user.
- [Custom IdP tokens](https://docs.diagrid.io/develop/agents/enterprise-identity/custom-idp-tokens) — Pass a token from your own identity provider when the Diagrid identity provider is not trusted.
- [Troubleshooting](https://docs.diagrid.io/develop/agents/enterprise-identity/troubleshooting) — Rejection codes and the operator debugging path for each one.