# Agent Identity & Audit Trail

An audit log that records *what* happened but not *who* did it is incomplete. In traditional systems, human identity is established at the authentication boundary and attributed to every subsequent action. AI agents present a harder problem: a single agent deployment may involve dozens of models, tools, and sub-agents acting autonomously — each capable of taking consequential actions without direct human intervention.

Highflame addresses this through [ZeroID](/agent-identity-zeroid/introduction.md), a cryptographic identity system for agents. Every action an agent takes through the Gateway carries a signed identity token that proves which agent acted, who authorized it, how deeply it was delegated, and what it was allowed to do. This creates a cryptographic audit trail: a record where identity claims are verifiable after the fact using the issuing authority's public keys — not just logged text.

***

## The identity token as an audit record

When an agent authenticates with ZeroID, it receives a short-lived JWT signed with an RS256 private key. Every request the agent makes to the Gateway includes this token. The Gateway validates it and extracts the identity claims before the request is processed.

A ZeroID token carries:

| Claim                       | What it records                                                                                   |
| --------------------------- | ------------------------------------------------------------------------------------------------- |
| `sub`                       | The SPIFFE URI of the agent acting: `spiffe://zeroid.dev/{account}/{project}/agent/{external_id}` |
| `identity_type`             | Classification: `agent`, `service`, `application`, `mcp_server`                                   |
| `sub_type`                  | Operational role: `orchestrator`, `autonomous`, `tool_agent`, `code_agent`, `evaluator`           |
| `trust_level`               | Platform confidence in the identity: `first_party`, `verified_third_party`, `unverified`          |
| `scopes`                    | The specific capabilities the token grants                                                        |
| `grant_type`                | Which OAuth flow was used to issue this token                                                     |
| `act.sub`                   | The SPIFFE URI of the delegating principal or the human user who authorized this agent            |
| `delegation_depth`          | How many hops deep in a delegation chain this token sits                                          |
| `account_id` / `project_id` | Tenant context                                                                                    |

The token is cryptographically signed. Any downstream system — including post-hoc audit tooling — can independently verify that a claim was issued by ZeroID and has not been tampered with, using the JWKS endpoint at `/.well-known/jwks.json`.

***

## Delegation chains and multi-agent accountability

In orchestrated deployments, a root orchestrator spawns sub-agents that in turn call tools. Without a delegation record, an audit trail might show a tool call happened but cannot attribute it back through the chain to the instruction that caused it or the human who authorized the session.

ZeroID's [token exchange flow](/agent-identity-zeroid/concepts/token-flows.md) (RFC 8693) solves this. When an orchestrator delegates to a sub-agent:

1. The orchestrator presents its own token and a signed assertion from the sub-agent
2. ZeroID verifies both, intersects the allowed scopes, and increments `delegation_depth`
3. The issued token's `sub` is the sub-agent; `act.sub` contains the orchestrator's identity
4. If the orchestrator was itself delegated, the full chain is preserved: `act.act.sub` carries the upstream principal

This means every action in the audit trail carries:

* **Who acted** — `sub` (the immediate agent)
* **Who authorized it** — `act.sub` (the orchestrating principal or human)
* **How deep the chain is** — `delegation_depth`
* **What it was allowed to do** — `scopes`

For a three-tier deployment (human → orchestrator → sub-agent → tool), every tool call is traceable back to the human session that initiated it, through cryptographically linked tokens rather than application-level logging.

***

## How identity propagates into the audit trail

The Gateway extracts ZeroID claims from every authenticated request and propagates them into Observatory telemetry:

**In traces:** Every span carries the agent's `sub` (SPIFFE URI), `trust_level`, `identity_type`, `sub_type`, and `delegation_depth`. For delegated requests, `act.sub` is recorded alongside `sub` so the full attribution is visible in the trace.

**In threat events:** Every Shield enforcement decision — block, redact, alert, monitor — records the agent identity claims alongside the detector signals and Cedar policy decisions. If an agent is blocked for a policy violation, the event record proves *which* agent was blocked, at what trust level, under what delegated authority.

**In the Audit Archive:** When archiving is enabled on a route, every record includes the full set of identity claims from the request token. The archive entry links a specific model input/output to a specific cryptographically-verified agent identity — not just an application label or API key.

This means that for any event in Observatory or Archive, the question "which agent did this, and who authorized it?" is answerable from the event record itself — without cross-referencing application logs.

***

## Cryptographic verification

The audit trail is cryptographic because identity claims can be verified independently:

1. **At request time** — the Gateway validates the JWT signature against the JWKS endpoint (`GET /.well-known/jwks.json`). Signing keys are refreshed every 5 minutes, with lazy refresh on unknown key IDs.
2. **At introspection time** — for sensitive operations, callers can call `POST /oauth2/token/introspect` to check whether a token is still active (`active: true`) or has been revoked. This is a live check against the identity's session state.
3. **After the fact** — because each token carries a `jti` (JWT ID), any historical event record that includes the raw token or its claims can be re-verified against the issuer's public key. The signature proves that ZeroID issued the claim, and the `jti` provides a unique event anchor for the specific issuance.

This is the distinction between a cryptographic audit trail and a conventional audit log: you are not trusting that the logging system recorded the right data — you are verifying that the identity presented at the time of the action was issued by a specific authority, for a specific agent, for a specific purpose.

***

## Continuous Access Evaluation signals

ZeroID supports Continuous Access Evaluation (CAE): real-time signals that invalidate agent identities without waiting for token expiry. These signals are governance events in their own right — each one is recorded with a timestamp, severity, source, and the identity it affected.

| Signal               | Governance meaning                                                                          |
| -------------------- | ------------------------------------------------------------------------------------------- |
| `session_revoked`    | Access withdrawn — agent was shut down, credentials compromised, or policy violated         |
| `credential_change`  | Credentials rotated — prior tokens issued before this point should not be trusted           |
| `anomalous_behavior` | Runtime anomaly detected — unusual request volume, unexpected scope usage, timing deviation |
| `policy_violation`   | Agent was found to have violated its defined operating policy                               |
| `ip_change`          | Agent reached the Gateway from an unexpected network location                               |
| `owner_change`       | Human responsibility for this identity has been transferred                                 |
| `retirement`         | Agent decommissioned — no further access should be granted                                  |

**Signal severity** escalates from `low` (informational) through `medium` (investigate) and `high` (immediate review) to `critical` (breach or emergency). Signals at `high` and `critical` trigger immediate session invalidation; token introspection returns `active: false` sub-second after ingestion.

**Signal history as an audit record:** Every signal is persisted against the identity it affects. For compliance and incident response, this creates a timeline of trust events — you can see exactly when a session was revoked, by whom, and for what reason.

***

## End-to-end: from action to accountable record

The complete identity governance chain for a request:

```
Agent authenticates with ZeroID
        │
        ▼ Short-lived RS256-signed JWT issued
        │  (sub, act.sub, trust_level, scopes, delegation_depth)
        │
Agent sends request to Gateway
        │
        ▼ Gateway validates JWT signature via JWKS
        │  Extracts identity claims
        │  Evaluates Shield policies (trust_level, scopes in Cedar context)
        │
        ▼ Request allowed / blocked / redacted
        │
        ▼ Observatory trace recorded
        │  (sub, act.sub, trust_level, delegation_depth in every span)
        │
        ▼ Threat event recorded (if policy fired)
        │  (agent identity + detector signals + determining policies)
        │
        ▼ Audit Archive record written (if enabled on route)
           (full token claims + request/response + Shield results)
```

At any point in this chain, the identity record is verifiable: the JWT signature anchors it to a specific ZeroID issuance, and the full claim set — including delegation history — is preserved in every downstream record.

***

## Related

* [Agent Identity (ZeroID)](/agent-identity-zeroid/introduction.md) — registering agents, issuing tokens, and managing identity lifecycle
* [Token Flows](/agent-identity-zeroid/concepts/token-flows.md) — which grant type to use, including token exchange for delegation chains
* [Signals and Revocation](/agent-identity-zeroid/guides/signals-and-revocation.md) — CAE signal types, severity levels, and revocation patterns
* [Audit Archive & Reporting](/governance-and-reporting/audit-archive.md) — capturing and retaining records that include identity claims
* [Observatory → Traces](/observatory/traces.md) — viewing agent identity in distributed trace spans


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.highflame.ai/governance-and-reporting/agent-identity-audit.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.