Identity Model

ZeroID models agents as identities, not as anonymous credentials. That distinction is what makes delegation, attribution, and revocation work cleanly across agentic systems.

Tenant Model

Every ZeroID resource belongs to a tenant:

• account_id

• project_id

Admin APIs are tenant-scoped. In the current server design, tenant context is provided through X-Account-ID and X-Project-ID headers on /api/v1/* routes.

Identity Types

ZeroID supports multiple identity types, so you can model real systems instead of collapsing everything into one generic service account:

Identity Type	Use It For
agent	Autonomous agents, orchestrators, tool agents, evaluators, assistants
application	Apps that host or invoke agent workflows
mcp_server	MCP servers and tool-serving infrastructure
service	Internal services or non-agent workloads

Agent Sub-Types

When identity_type is agent ZeroID supports sub-types such as:

• orchestrator

• autonomous

• tool_agent

• human_proxy

• evaluator

• chatbot

• assistant

• code_agent

• custom

Use subtypes to preserve the identity's operational role in both registry data and issued tokens.

WIMSE/SPIFFE URI

Each identity gets a stable URI in this shape:

spiffe://{domain}/{account_id}/{project_id}/{identity_type}/{external_id}

Example:

spiffe://zeroid.dev/acct-demo/proj-prod/agent/billing-orchestrator

This URI becomes the canonical machine identity. For most non-human flows, it is also the JWT sub claim.

Important Identity Fields

These fields show up repeatedly across the registry, policies, and JWTs:

Field	Meaning
external_id	Your stable application-level identifier
name	Human-readable display name
trust_level	How much confidence the platform has in the identity
allowed_scopes	Scopes the identity may request
public_key_pem	Public key for signed assertion flows like jwt_bearer
framework	Optional framework metadata such as langgraph, autogen, or crewai
capabilities	JSON metadata for what the identity can do
labels	Flat key-value labels for indexing and policy context

Owner vs Principal vs Actor

These are easy to mix up. Keep them separate:

Field	Meaning
owner_user_id	The user who registered or owns the identity
sub	The principal currently authenticated by the token
act.sub	The principal that delegated authority, or the end user on whose behalf the agent is acting

Examples:

• A direct autonomous agent token usually has sub = spiffe://.../agent/foo and no act.

• A delegated token usually has sub = sub-agent URI and act.sub = orchestrator URI.

• A user-context token may have sub = agent URI and act.sub = end-user ID.

Trust Levels

ZeroID uses trust levels as a compact signal for downstream authorization and issuance policy:

• unverified

• verified_third_party

• first_party

Trust level is not the same thing as authorization. It is an input into policy and a useful claim for downstream systems.

Identity Lifecycle

Identities move through lifecycle states:

• active

• suspended

• deactivated

Deactivation matters operationally because tokens and keys tied to the identity may need to be rotated or revoked when the identity is no longer usable.

Why This Model Matters

If you only keep a client ID or a service account name, you lose most of the context that agentic systems need:

• What kind of workload is acting

• Which system owns it

• Whether it is allowed to delegate

• How much should it be trusted

• Who authorized it in a multi-step chain

ZeroID keeps the identity context available at issuance and stores it within the JWT itself.

What's Next?

• Read Token Flows to map this identity model onto actual OAuth and delegation patterns.

• Read Agent Delegation if you are building orchestrator and sub-agent workflows.