Downstream Authorization

Pattern for verifying ZeroID JWTs in downstream services — verify() for local fast checks, session() for revocation-aware checks, then extract claims before calling Shield.

ZeroID answers identity and delegation questions at token issuance time. Your downstream service still needs to decide whether the current principal is allowed to perform the requested action.

This guide covers the standard pattern for consuming ZeroID tokens in APIs, services, MCP servers, and internal tools.

What A Downstream Service Should Verify

At minimum:

1. verify the JWT signature using ZeroID's JWKS

2. verify issuer and expiry

3. inspect sub, scopes, and any application-specific claims

4. inspect act.sub when delegation context matters

5. enforce authorization locally

Fetch the JWKS

ZeroID publishes public keys at:

GET /.well-known/jwks.json

A downstream service can cache the JWKS and select the right key using the JWT kid header.

Claims That Usually Matter Most

Claim	How To Use It
sub	The currently authenticated principal
scopes	Scope-based authorization
act.sub	Audit and delegation-aware authorization
trust_level	Risk-sensitive decisions or routing
identity_type	Differentiate agents, services, applications, and MCP servers
sub_type	Differentiate orchestrators from tool agents or code agents
delegation_depth	Reject deeper chains if your service only supports shallow delegation
owner_user_id	Operational attribution, not direct runtime auth

Typical Authorization Patterns

Scope-Based Checks

Example:

• require data:read to fetch a record

• require tickets:write to update a ticket

Identity-Type Checks

Example:

• allow only service or agent principals to call an internal API

• reject application identities from low-level infrastructure routes

Delegation-Aware Checks

Example:

• allow tool_agent identities only if act.sub belongs to an approved orchestrator

• reject delegated chains deeper than 1

Trust-Level Checks

Example:

• allow first_party identities to call privileged internal tools

• require verified_third_party or better for external integrations

Example Decision Logic

A downstream invoice service might enforce:

• scope must include invoice:write

• identity_type must be agent or service

• if sub_type is tool_agent, act.sub must be present

• trust_level must be first_party

That is enough to distinguish:

• direct autonomous agents

• orchestrators delegating to tool agents

• background services

Introspection vs Local Verification

You have two broad options:

Local Verification

Use this when:

• you want low latency

• your service can trust cached JWKS

• you are comfortable enforcing auth from token contents alone

Introspection

Use this when:

• you need a stronger online check of token activity

• you want the latest revocation state

• your authorization model already depends on live identity state

Introspection endpoint:

POST /oauth2/token/introspect

In practice, many systems do local verification for hot paths and reserve introspection for sensitive operations or high-risk environments.

Highflame Integration Pattern

If you are already using the Highflame platform, ZeroID complements it cleanly:

• ZeroID establishes who the agent is

• Highflame guardrails and policy systems decide what the agent can do

That means ZeroID JWT claims can feed downstream authorization, policy evaluation, guardrails, and observability with a consistent identity model.

What's Next?

• Read SDK Overview if you want to integrate token issuance and admin workflows from code.

• Revisit Identity Model if you need to design claim-driven authorization rules.