Identity Layer

The Identity Layer gives ContextOS stable names for two different things:

• business entities the runtime talks about, such as customers, orders, policies, documents, and tools;
• actors that execute work, such as delegated users, agents, gateways, and adapters.

Stable identity is what lets the runtime bind evidence to entities, bind actions to authority, and replay a run without guessing which object or actor a model meant.

Definition

The Identity Layer owns:

The Ontology defines entity types, relationships, constraints, and classification rules. The Identity Layer generates and resolves identifiers for those entities.

Profile-aware execution adds authenticated PrincipalRef, bounded AuthorityGrant chains and current verification/revocation observations through the Execution Contract. Stable names, principal-chain strings and hashes are references to evidence; none authenticates the actor or grants authority by itself. The reference validates normalized broker facts and does not implement an identity provider or signature verifier.

Why it exists

Without a formal identity layer:

• a plan may refer to ord_881 while a tool expects a different upstream ID;
• memory may store human-readable names that collide or leak PII;
• evidence may cite a record without the source-system mapping needed for audit;
• a tool call may blur the delegated user and the agent workload;
• replay may not know which entity version or actor authority was active.

ContextOS separates those concerns so every run can answer who acted, on whose behalf, against which entity, using which authority.

How it works

Entity identity

CEID

A Canonical Entity ID is the default reference token for agent-visible artifacts.

ceid:{entity_type}:{slug}:{suffix}

Examples:

ceid:order:ord-881:6fa2
ceid:customer:cus-77:91bd
ceid:policy:refund-threshold-high:0b7e

CEIDs are not primary keys. They are stable handles that resolve to source-system IDs through a mapping store. Old CEIDs remain resolvable as aliases after renames, merges, and migrations.

SID

A Semantic ID is a model-facing feature identity, usually produced from embeddings or other side information.

sid:{entity_type}:{sid_model_version}:{token_sequence}

SIDs are useful for retrieval, ranking, recommendation, and other ML systems. They are not suitable as audit handles because they may be regenerated when the feature model changes.

Hard Rules

Actor identity

Every governed run identifies a user and an agent workload, but it does not always use delegated human authority or the optional signed-claim profile. The implementation lesson is that “agent identity” cannot be a single string. ContextOS can bind up to four linked facts:

1. Registry identity — the durable agent subject, such as agent:contextos/support-refund@1.2.0.
2. Workload identity — the runtime or service identity that proves where the agent is executing, usually SPIFFE-style.
3. Delegation chain — the ordered principals the run is acting for: human, service, automation, parent agent, child agent.
4. Run claim profile — an optional short-lived signed claim binding subject, chain, scopes, run ID, tenant, expiry, and key ID.

The Tool Gateway should never treat the agent as the user. It always checks the agent workload; when the action uses delegated user authority, it also validates that delegation and the agent’s permission to use it for the capability.

Agent identity subject

ContextOS uses a versioned agent URN for the audit subject:

agent:contextos/{slug}@{semver}

Examples:

agent:contextos/support-refund@1.2.0
agent:contextos/incident-commander@0.9.4
agent:contextos/data-steward@2.0.0

The URN is not the process identity. It names the agent behavior contract: manifest, owner, lifecycle, policy ceiling, tool surface, prompt pack, and runtime profile. The workload identity proves the process. When the optional identity-claim profile is adopted, the signed claim binds the process and behavior contract to one run.

Ownership and lifecycle

Every registered agent should have structured ownership:

{
  "agent_urn": "agent:contextos/support-refund@1.2.0",
  "owner": {
    "owner_id": "team_support_ops",
    "owner_kind": "team",
    "tenant_id": "tenant_acme_prod",
    "created_by": "usr_platform_admin_11",
    "signing_key_id": "kid_ctxos_support_2026_05",
    "lifecycle": "active"
  },
  "identity_scopes": ["tools:read", "tools:write", "a2a:send"]
}

lifecycle is part of authorization, not decoration. A revoked agent cannot receive new run claims, appear in active discovery, or execute A2A work. A deprecated agent may remain replayable but should not be selected for new runs unless policy explicitly allows a migration window.

Principal chain and on-behalf-of

The principal chain records who the run is for and how authority was delegated. It is ordered oldest-first and should be narrowed, not expanded, at each hop.

[
  { "kind": "user", "id": "usr_771", "tenant_id": "tenant_acme_prod" },
  { "kind": "agent", "id": "agent:contextos/support-refund@1.2.0", "tenant_id": "tenant_acme_prod" },
  { "kind": "agent", "id": "agent:contextos/refund-policy-checker@0.4.0", "tenant_id": "tenant_acme_prod" }
]

A child agent does not inherit the parent’s bearer credential. The canonical delegation envelope binds a narrower scope and budget. When the identity-claim profile is adopted, the child also receives a fresh claim whose principal chain points back to the original principals, with a smaller scope set and shorter expiry.

For the additive execution profiles, validateAuthority binds workload/person-directed mandate, audience, tenant, root/child run links, purpose, exact capability, resources, destinations, argument constraints, data labels, explicit currency/amount and validity. Every child grant intersects every ancestor, with current ancestor revocation and bounded depth; a parent grant cannot mint extra budget. A person-directed mandate must trace to its authenticated owner. Personal and employer namespaces/credentials remain separately scoped even on one device.

The optional ctxid/1 signed-claim representation below remains a base integration choice. It is distinct from selecting a standard contextos.*@1 execution profile: authenticated identity is mandatory for those profiles, while the concrete token/attestation mechanism is deployment-specific. Trusted brokers must verify issuer, signature/attestation, audience and current validity before constructing normalized observations. A caller-supplied verification_status: "verified" is not proof.

Identity claim profile

The optional run claim is a portable proof carried by RunContext and referenced by A2A/tool/audit artifacts in deployments that adopt this profile.

{
  "version": "ctxid/1",
  "iss": "contextos:identity",
  "sub": "agent:contextos/support-refund@1.2.0",
  "aud": "contextos:runtime",
  "run_id": "run_a1b2c3d4e5f60718",
  "tenant_id": "tenant_acme_prod",
  "principal_chain": [
    { "kind": "user", "id": "usr_771", "tenant_id": "tenant_acme_prod" }
  ],
  "scopes": ["tools:read", "tools:write", "a2a:send"],
  "nbf": "2026-05-17T10:00:00Z",
  "exp": "2026-05-17T10:05:00Z",
  "kid": "kid_ctxos_support_2026_05",
  "claim_hash": "sha256:...",
  "sig": "..."
}

Minimum rules:

• Claims are short-lived and scoped to one run, session, or A2A hop.
• Child claims must be narrower than parent claims and cannot carry agent:spawn/a2a:send unless policy explicitly permits delegation.
• Tool scopes are an intersection of requested scopes, manifest ceiling, delegated-user scopes, adapter permissions, native-risk policy, and the v1 safety ceiling.
• Claim hashes, not raw secrets, are what operators should see in traces and dashboards.

Credential exchange

For work using external credentials, long-lived secrets should not reach the model or Planner. The boundary pattern is:

1. Validate workload identity and tenant scope, plus delegated user authority, registry lifecycle, and signed run claim when those optional surfaces apply.
2. Evaluate policy, manifest scope ceiling, tool, native-risk dimensions, actual arguments, and approval obligations.
3. Mint a short-lived execution credential scoped to one action.
4. Invoke the adapter through the Tool Gateway.
5. Persist credential exchange metadata, policy decision ID, identity claim hash, trace ID, and receipt.

Bind the brokered credential to the actual destination and active execution boundary, and never expose its bearer value in prompts, memory, tool metadata or telemetry. Required broker/revocation outages block the dependent action; cached authority is usable only within an explicitly trusted freshness window. Wake, redirect, retry, delegation and resume recheck current authority rather than replaying old consent. Conformance requires real broker/negative-case evidence before a runtime claim.

sequenceDiagram
  participant User as User
  participant Agent as Agent Runtime
  participant Identity as Identity Layer
  participant Gateway as Tool Gateway
  participant Tool as Tool Adapter
 
  User->>Agent: Request with delegated auth context
  Agent->>Identity: Validate user delegation and agent workload
  Identity-->>Agent: Bound authority + optional signed claim
  Agent->>Gateway: ToolCallEnvelope with claims, tenant, trace, CEIDs
  Gateway->>Gateway: AuthN/AuthZ, policy, ActionRisk, approval, parameter checks
  Gateway->>Tool: Invoke with short-lived execution credential
  Tool-->>Gateway: Result and receipt
  Gateway-->>Agent: ToolResultEnvelope, policy_decision_id, citations

Resolution model

Entity resolution should preserve both audit readability and system-specific precision.

{
  "ceid": "ceid:order:ord-881:6fa2",
  "entity_type": "order",
  "entity_key": "ent_01JFG2",
  "is_canonical": true,
  "aliases": ["ceid:order:legacy-881:83bb"],
  "source_mappings": [
    {
      "system": "orders_db",
      "source_id": "ord_881",
      "confidence": 1.0
    }
  ],
  "classification": "INTERNAL",
  "ontology_version": "ont.support@1.0.0",
  "ceid_policy_version": "ceid-policy@2.0.0"
}

Tool adapters resolve CEIDs to source IDs at the boundary. Agent prompts, plans, evidence refs, and memory records should keep CEIDs.

Effective authority graph

Identity inventory is not enough to answer what an agent can actually do. Operators maintain an effective authority graph whose nodes include users, workload identities, service principals, agents, sessions, credentials, tools, capabilities, destinations, datasets, resources, and approval roles. Directed edges represent ownership, delegation, assumption, credential exchange, capability access, data reach, and revocation dependency.

For a proposed action, effective authority is the set of reachable effect paths after intersecting:

principal chain ∩ live delegation ∩ agent manifest ceiling
∩ policy ∩ surfaced capability ∩ technical containment ∩ valid approval

The graph is an operational view composed from canonical identity claims, policy, tool manifests, and audit rows—not a second authorization engine. The deterministic gateway remains the enforcement point. The view exists so security and operations can answer which principal can reach which effect, through which credential and delegation chain, with which data and recovery exposure.

Every production release stores a baseline graph projection. New or widened paths are authority drift and require an owner, reason, review, and expiry or explicit acceptance. A kill switch is implemented as graph revocation: disable the agent registration, delegation edge, credential exchange, capability, destination, or release tuple, then verify that no alternate path remains reachable.

Interfaces

For profile-aware runs, the separate ActionBinding, AuthorityValidationInput, grant observations and verified run links correlate with these base fields through trusted admission. They add no required property to the closed base envelopes. Attachment schema entry points define their structure; scope intersection, freshness and authenticity still need semantic checks and trusted runtime adapters.

Operational concerns

Governance rules

• Do not embed raw PII in CEID slugs unless a policy explicitly allows it.
• Keep source-system mappings access controlled and audited.
• Treat CEID resolution as a governed read when the source mapping is sensitive.
• Preserve aliases rather than rewriting old evidence or memory.
• Version SID generators and tokenizers; never rely on SID stability across versions.
• Preserve agent workload identity for every governed call and delegated user authority whenever it is actually used. Tool envelopes carry the principal chain/auth reference; DecisionRecord correlates through lineage and trace.
• For cross-tenant workflows, require explicit tenant scope on every resolution and tool call.
• Treat agent lifecycle as an authorization input; revoked agents fail closed.
• When the signed-claim profile is enabled, rotate keys under change control and retain historical verification material for its declared replay window.
• When the identity-claim profile is enabled, emit claim subject/hash/scope metadata with correlated tool, A2A, policy, and decision audit evidence; never expose raw secrets.

Failure modes

Evaluation metrics

• CEID uniqueness and collision rate.
• CEID resolution success rate and latency.
• Alias coverage for renamed or merged entities.
• Percentage of planner steps and evidence refs using CEIDs instead of raw source IDs.
• Tool calls with workload identity present, and delegated authority present when native authority is user_delegated.
• Signed-claim coverage and verification failures among deployments or workflows that require the profile.
• Claim verification failure rate by reason: expired, bad signature, missing scope, tenant mismatch.
• Revoked-agent execution attempts denied.
• Key rotation age and trusted-previous-key window.
• Credential exchange failure rate by authority and native-risk slice, with v1 mode retained for compatibility dashboards.
• SID churn and retrieval quality delta by SID version.
• Cross-tenant resolution denial rate.
• Effective-authority path count and newly reachable high-risk paths by release.
• Authority-drift detection latency and stale delegation-edge age.
• Revocation propagation time and post-kill-switch reachable-path count (target: zero for the revoked scope).

Example

For a refund request, this identity-focused excerpt shows the optional signed-claim profile:

{
  "run_context": {
    "tenant_id": "tenant_acme_prod",
    "user": {
      "user_id": "usr_771",
      "delegation": {
        "auth_type": "oauth2",
        "subject": "u:user:771",
        "scopes": ["orders.read", "payments.refund"]
      }
    },
    "agent": {
      "agent_id": "agt_support",
      "agent_urn": "agent:contextos/support-refund@1.2.0",
      "workload_identity": "spiffe://contextos/agents/support",
      "role": "support_ops",
      "identity_claim": {
        "version": "ctxid/1",
        "iss": "contextos:identity",
        "sub": "agent:contextos/support-refund@1.2.0",
        "run_id": "run_a1b2c3d4e5f60718",
        "tenant_id": "tenant_acme_prod",
        "principal_chain": [
          { "kind": "user", "id": "usr_771", "tenant_id": "tenant_acme_prod" },
          { "kind": "agent", "id": "agent:contextos/support-refund@1.2.0", "tenant_id": "tenant_acme_prod" }
        ],
        "scopes": ["tools:read", "tools:write"],
        "nbf": "2026-09-03T08:00:00Z",
        "exp": "2026-09-03T08:05:00Z",
        "kid": "kid_ctxos_support_2026_09",
        "claim_hash": "sha256:..."
      }
    }
  },
  "entities": {
    "order": "ceid:order:ord-881:6fa2",
    "customer": "ceid:customer:cus-77:91bd"
  }
}

The Planner and Critic reason over CEIDs. The Tool Gateway resolves ceid:order:ord-881:6fa2 to the orders system ID only after policy and identity checks pass.

Common misconceptions

• “CEIDs replace database IDs.” They do not. They give ContextOS a stable audit handle that maps to source IDs.
• “SIDs are better CEIDs.” They are not. SIDs are model features and can change across versions.
• “The agent always acts as the user.” The agent has its own workload identity; user delegation is preserved only when the action actually uses that authority.
• “Identity is only an Intelligence-plane concern.” Entity identity is Intelligence-plane work; execution authority is Trust-plane work.

Related Docs

• Ontology
• Knowledge Graph
• Governance
• Adapter Mesh
• API Contracts