Identity & actors

Every authorization decision starts with identity. Before policy runs, the gateway resolves the caller into a normalized actor — a consistent shape regardless of how the request was authenticated.

What an actor is

An actor carries the identifiers that policy and audit reason about:

• Subject — the human user, when present (from your IdP).
• Agent — the registered AI agent acting on the user’s behalf.
• Service account / workload — non‑human callers (CI, a platform, a mapped workload identity).
• Client surface — where the request entered (e.g. an external chat surface vs. an internal tool). Policy can allow a tool on one surface and deny it on another.
• Tenant & environment — the gateway scope the request runs in.

These come from different places depending on the authentication mode, but downstream they are one normalized actor.

Claim mapping (OIDC)

In oidc_jwt mode the gateway validates the JWT (issuer, audience, signing key) and maps claims onto the actor model — user id, groups, tenant, environment, client surface, and any service/workload identifiers. Groups feed role bindings; the surface and environment feed policy context.

Agents act on behalf of users

An agent has its own identity, owner, and scope, and carries the delegated user context. Policy can require both to line up — “this agent may call this tool only when acting for a user in this group, on this surface, in this environment.” See Agents.

Why a 403 might not be a policy problem

If a call is denied, first confirm the actor the gateway resolved — GET /v1/identity/me returns your normalized actor and computed permissions. A missing group or surface mismatch is an identity issue, not a policy bug.

See it illustrated See how IdP claims become a normalized actor and feed policy, illustrated.