| Claim | Meaning |
|---|---|
iss, sub, jti, iat, nbf, exp | Issuer, agent ID, token ID, times |
aud | The single audience the token is for. It must be requested and on the agent's allowlist, and the Oathera Identity Service checks it |
tenant_id | The tenant |
cnf (cnf.jwk) | The session public key (RFC 7800) |
anchor_jkt, key_epoch, revocation_epoch | The anchor key digest and the epochs the token was issued under |
principal | The person who approved the agent |
capabilities | What the agent may do; a capability can be privileged |
task_policy, assurance | The task policy and the assurance of the evidence behind the token |
agent_label, platform | From the enrollment record |
| Risk tier | From the NHI attributes, when sent |
| Host posture | Truncated host digest, host confidence, host_attested, findings count, drift |
| Enrollment attribute block | Sponsor, operational boundary and tier (the requested clearance) |
clearance | The granted clearance, never more than the evidence supports |
Developers
Your agent authenticates with a token anyone can copy.
A copied token works from any machine, and every request looks the same, whichever agent or copy sent it. Oathera binds the agent's identity to a key created on its host, compares the host at every token, and requires a proof signed by an in-memory session key on every call. This section covers the components, how to run them beside an agent, the token and its claims, and the standards.
Components
Three Oathera components. The Oathera Witness runs on each host where agents run. The Oathera MCP Plugin has two capabilities on your MCP server, Oathera Agent Enrollment and Oathera Agent Enforcement; together they are the enforcement plane, in your environment. The Oathera Identity Service is the control plane, in Oathera's cloud. Your identity provider, MCP servers, policy engine and resource servers stay yours.
- Oathera Agent Enrollment. An MCP server, over stdio by default, or Streamable HTTP at
/mcpwhenIDENTITY_MCP_PORTis set, with workload authentication set byIDENTITY_MCP_AUTH_MODE(defaultbearer). Tools:enroll,issue_token,status,sign_request,sign_operation. - Oathera Identity Service. Holds the register of approved agents and their enrollment records, issues identity tokens and signs boundary decisions.
- Oathera Agent Enforcement. Runs in your MCP server, in front of its tools: in process with a Node MCP SDK server, or as a proxy in front of a stdio or Streamable HTTP server in any language. Verifies the identity token and the operation proof, requests a boundary decision, and sends the resource server a gateway assertion.
- Oathera Witness. A small service on each host, installed by IT and run as root in production, that watches the agents there from the operating system and vouches for what it saw in a signed report. Oathera Agent Enforcement checks the report before policy uses it. A developer install runs it without root.
- Credential service (VCI). Issues W3C verifiable credentials when
CREDENTIAL_FORMAT=vc(defaultjson). - Protected core. Both MCPs load the native
oathera-coreonly after verifying its Ed25519 release signature and SHA-256, re-verify it before security-critical operations and on a timer, and fail closed. Required by default;OATHERA_CORE_REQUIRED=falseallows a JavaScript fallback outside production. Token, proof and decision signature checks in Oathera Agent Enforcement run in JavaScript. The hosted simulator ships a signed core and its release key.
Put Oathera beside an agent
Bring your own agent (BYOA). The MCP bundle runs three things on the developer's machine, in the demo profile, pointed at the hosted Oathera Identity Service by default:
- Oathera Agent Enrollment, Streamable HTTP on port 4002;
- Oathera Agent Enforcement, on port 5003;
- a sample resource server.
AIS_URL points the bundle at another Oathera Identity Service. Claude Code adds the two MCPs as oathera-identity and oathera-gateway. The bundle needs a signed protected core for the developer's platform, Linux x64 or arm64 by default.
Flow: the agent calls enroll; a principal approves at the activation URL; the agent calls issue_token; before each tool call it calls sign_operation and passes the token and the proof to Oathera Agent Enforcement.
Oathera Agent Enforcement
- In-process.
attachOatheraGatewayattaches to a Node MCP SDK server; the demo Oathera Agent Enforcement uses it. - Proxy.
createOatheraGatewayProxysits in front of a stdio or Streamable HTTP MCP server written in any language. - Schema. Enforced tools gain
identity_tokenand proof fields in their input schema. - Audit. Every enforced call writes one
boundary_decisionevent; every unenforced call writes onegateway_unenforced_callevent. - Default deny. With
GATEWAY_DEFAULT_DENY=true, a tool with no enforcement entry is refusedoperation_not_configured. Defaultfalseoutside production, where default deny is always on. With it off, a listed but unconfigured tool passes through unenforced and is logged; an unlisted tool is refusedunknown_tool. - Argument allow-lists. Arguments outside a tool's allow-list are refused.
- No identity token. A call without one is refused
invalid_tokenlocally, before any Oathera Identity Service or tool call, and logged as a deny event. The console lists the agent that made it, so an administrator can enroll or reject it.
Enrollment
- On start, Oathera Agent Enrollment's key provider creates an Ed25519 anchor key: a software key in a
.keysdirectory next toIDENTITY_STATE_PATH, mode 0600, directory 0700. The agent identifier derives from the anchor key's key digest, the SHA-256 JWK digest of RFC 7638. No expiry; it lasts until revoked. enrollasks the agent for its attributes through an MCP form: agent type, capabilities, model, OS, version, AI providers and AI models.- It builds the enrollment attribute block (agent identifier, label, platform, sponsor block, operational boundary with the requested clearance) and validates it locally with the Oathera Identity Service's validator, stopping with
invalid_enrollment_attributeson a malformed block. - It observes the host and computes the host digest.
POST /enroll/startcarries the full anchor public key, signed by the anchor key under RFC 9421. The response holds an activation URL with a single-use activation code that expires in 10 minutes.- The principal signs in at the IdP with OIDC authorization code and PKCE S256. Sign-in state, PKCE verifier and nonce are bound to the anchor key being enrolled. The approval page shows the requested and the granted clearance.
- The Oathera Identity Service writes the enrollment record atomically: anchor key, principal (
iss,sub, email, email verified, name, groups), label, platform, enrollment attribute block, host block with attestation status, findings and confidence, NHI attributes with risk tier, key and revocation epochs. - Oathera Agent Enrollment verifies the signed activation (
typ oathera-auth-activation+jws, at most 300 s) against the Oathera Identity Service's keys and its own anchor key.
- Sponsor. The enrollment attribute block carries a sponsor block, the person or organization who answers for the agent. The sponsor is collected and checked against your proofing sources.
- NHI attributes. Optional self-reported answers to the OWASP NHI questionnaire. The Oathera Identity Service derives a risk tier from 1 to 4 and NHI1 to NHI10 findings. The risk tier appears as a token claim.
- Requested clearance.
IDENTITY_MCP_REQUESTED_CLEARANCE0, 1 or 2, default 0. The granted clearance is the lower of the request and what the evidence supports. - Anchor rotation.
POST /agents/rotate-anchor, signed by the new anchor key and carrying an authorization artifact, raises the key epoch by one. - SPIFFE evidence. A SPIRE-issued JWT-SVID as optional enrollment evidence, verified for an allow-listed trust domain (
TRUSTED_SPIFFE_DOMAINS) and bound to the proposed anchor key by a single-use challenge. Without a trusted domain the endpoint answers403 spiffe_not_configured. - Hardware or KMS custody. The production key-provider boundary accepts kms, cloud-kms, hsm, tpm, secure-enclave, os-keychain and workload-secret-manager backends and rejects private key material from any driver.
Host digest and host binding
- Inputs. SHA-256 over machine ID, hostname, platform, architecture, CPU model, CPU count, total memory, sorted MAC addresses and the cloud instance ID. Uptime, PID and boot time are excluded, so a reboot is not a new host.
- Machine ID. Linux reads
/etc/machine-id, then/var/lib/dbus/machine-id, then DMIproduct_uuid. macOS readsIOPlatformUUID. Windows readsMachineGuid. - Privacy. Identifying values are hashed by default with a salt derived from the anchor key.
- Comparison. At each token request the host is observed again on the agent's machine and its digest sent; the Oathera Identity Service compares it with the enrollment record. The comparison runs only when a digest is reported;
HOST_DISCOVERY_LEVEL=offreports none. HOST_BINDING.offskips the comparison.warn, the default and intended for testing and design partners, records a high-severity host-change alert, issues the token and marks it with a host-drift claim.enforcerefuses with403 host_changed.HOST_REQUIRE_ATTESTATION=on. Also refuses a token unless the host has a verified, key-bound platform attestation. Default off. On GCP, an instance identity token whose audience is the agent's anchor key reaches verified. On AWS the signature is verified whenAWS_IDENTITY_CERT_PEMis set, but the document is not bound to the key. On Azure the document is bound by a nonce, but chain verification is not implemented.- Code digest. Oathera Agent Enrollment hashes its own code and lockfile, not the agent's code. A change raises an alert when the agent re-enrolls.
- Evidence grades. A gate grades evidence as self-reported, corroborated or verified, and never lets self-reported evidence meet a policy that needs attestation. Host attestation status (verified, unbound, unverified) and host confidence 1 to 4 are recorded at enrollment.
The identity token
Each issuance creates a new Ed25519 session key in memory and destroys the previous one. Session keys are never written to disk. The anchor key signs a key-binding JWT (typ oathera-auth-keybind+jwt, 120 s, single-use jti) that names the new session key, and the token request is refused if the jti was seen before. Unknown and revoked agents, and agents whose principal is inactive, get no token.
The token is a JWT, EdDSA, with these claims.
Lifetime is 300 s, or 60 s when any capability is privileged. AGENT_TOKEN_LIFETIME (120 s) sets the lifetime of the v1 token only. A token is reused until 80% of its life has passed, and checks that cnf names the new session key before using a new token. In credential (VC) mode the token carries neither clearance nor the requested clearance unless issuance falls back to JSON.
Refresh on challenge. When a resource answers 401 with an identity-token requirement, Oathera's sample agent client refreshes once and retries.
The operation proof
The agent calls sign_operation, which signs with the session key. Oathera Agent Enrollment checks that the operation is one it knows and that the workload may sign; an unknown operation is refused invalid_operation. It also checks the capability and the audience.
- Fields. A compact JWS (
typ oathera-auth-operation-proof+jws, EdDSA) binding tenant, agent, audience, operation, arguments hash, token hash, task-context, delegation and approval hashes, and a 192-bit nonce. Lifetime at most 60 s. - Gateway checks. Validates the token, verifies the proof with the token's
cnfkey, compares every field, and only then consumes the nonce. A token without its session key is refused, and a replayed proof is refused. - Not RFC 9421. RFC 9421 signs Oathera's HTTP calls: enrollment, token requests, Gateway-to-identity-service decision requests and the direct resource path.
sign_request. Signs an HTTP request with the session key and attaches the identity token with a key-binding JWT. Off in the production profile unlessIDENTITY_MCP_SIGN_REQUEST_ALLOWLISTpins exact requests.- Content trust. Model-supplied arguments are labelled as agent content and can't set protected security fields. Content is not inspected for injection.
- Task context, delegation, operation approval. A signed task context bounds what the agent is doing, a delegation to a sub-agent can only narrow authority, and a single-use approval binds one exact operation to its arguments. Oathera Agent Enforcement checks all three.
Boundary decision and gateway assertion
- Boundary decision. Oathera Agent Enforcement sends a signed
POST /gateway/decision. The Oathera Identity Service checks that the gateway is approved (AIS_APPROVED_GATEWAYS), then the token (key, issuer,cnf, subject, expiry;audwhen present), the agent's status, and that the principal's email is verified and the principal is active. It returns a JWS (typ oathera-auth-boundary-decision+jws, 15 s by default, at most 30 s) bound to that gateway and request. The gateway uses each decision once and refuses the call if no valid decision arrives. - Boundary check. The boundary check covers clearance against each operation's floor and the boundary's
resourceslist. Credential status is checked in VC mode. - Gateway assertion. After an allow, Oathera Agent Enforcement sends the resource server a request-bound EdDSA JWS of at most 30 s in place of the token, used once and naming one resource audience. The resource server refuses an assertion made for another.
- Decision replay across replicas. Used decisions are kept in a replay store. A process-local store covers one Oathera Agent Enforcement replica; a shared store (
REPLAY_STOREset toredis,valkeyordurable, or an injected store) covers several.
Lifetimes and revocation
| Lifetime | What |
|---|---|
| For the agent's life on a host | Anchor key, agent identifier, enrollment record, enrollment attribute block, NHI attributes, host digest, principal, requested clearance |
| Per token: 300 s, or 60 s when a capability is privileged | Session key, identity token with its granted clearance, host comparison |
| Per call | Operation proof (single use), boundary decision (single use, at most 30 s), gateway assertion (single use, at most 30 s) |
- Revoke an agent. From the Oathera Identity Service's
/agentspage: raises its revocation epoch and marks it revoked. Its next token request and next boundary decision are refused. Tokens already issued stay valid untilexp; revocation is not pushed. - Principal deprovisioning. An Oathera Identity Service endpoint marks every agent of one principal deprovisioned, so their tokens and decisions are refused.
- Revocation snapshots. Signed snapshots by risk tier, 2 s for risk tier 1 to 300 s for risk tier 4.
- Audit log. Each security decision is linked into a hash chain in memory; credential-like values are replaced by an HMAC correlation ID. The chain is sealed in signed batches, verified, and exported exactly once to a SIEM or WORM sink.
- Telemetry. Signed telemetry batches from both MCPs with
OATHERA_TELEMETRY=on, which feed the console's decision, posture, Oathera Agent Enrollment, MCP Gateway, assurance and agent-risk screens. Each MCP registers with the control plane under the customer's license key when it starts and signs its telemetry with the key that registration returns. - Admin roles. The Oathera Identity Service's admin guard (
ADMIN_AUTH_MODE) adds sessions, step-up reauthentication for high-risk actions, refusal of agent tokens, and role checks with separation of duties. The console has its own sign-in with admin and viewer team roles and a step-up code to create a team.
Settings
| Setting | Where | Default |
|---|---|---|
HOST_BINDING | Oathera Identity Service | warn (also off, enforce) |
HOST_REQUIRE_ATTESTATION | Oathera Identity Service | off |
AGENT_TOKEN_LIFETIME | Oathera Identity Service | 120 s (the v1 token only) |
CREDENTIAL_FORMAT | Oathera Identity Service | json (or vc) |
AIS_APPROVED_GATEWAYS | Oathera Identity Service | |
TRUSTED_SPIFFE_DOMAINS | Oathera Identity Service | unset |
ADMIN_AUTH_MODE | Oathera Identity Service | none |
IDENTITY_MCP_REQUESTED_CLEARANCE | Oathera Agent Enrollment | 0 |
HOST_DISCOVERY_LEVEL, _PII, _SALT, HOST_CLOUD_PROBE | Oathera Agent Enrollment | |
IDENTITY_STATE_PATH, AIS_URL | Oathera Agent Enrollment | Hosted Oathera Identity Service in the bundle |
GATEWAY_AIS_DECISION_URL | Oathera Agent Enforcement | Set in the demo profile |
GATEWAY_DEFAULT_DENY | Oathera Agent Enforcement | false outside production |
OATHERA_CORE_REQUIRED | Both MCPs | required |
OATHERA_TELEMETRY | Both MCPs | off |
REPLAY_STORE | Oathera Agent Enforcement | process-local (also redis, valkey, durable) |
OATHERA_PROFILE | All | demo in every hosted service |
Product settings use the OATHERA_ prefix; the legacy prefix is still read, with a one-time deprecation log.
Standards
| Standard | How Oathera uses it |
|---|---|
| JWT, JWS, EdDSA | Every token, activation, decision and assertion |
cnf (RFC 7800), JWK digest (RFC 7638) | The token names its session key; the agent identity derives from the anchor key's digest |
| RFC 9421 and a signing-key header | Proof of key possession on Oathera's HTTP calls. The header is an Oathera profile aligned toward draft-hardt-httpbis-signature-key |
| OIDC with PKCE | The principal signs in at your IdP (OIDC_ISSUER); the hosted demo uses an internal demo IdP |
| W3C VC 1.1, Ed25519Signature2020 | Agent, sponsor and operational-boundary credentials with suspend, reinstate and revoke, when CREDENTIAL_FORMAT=vc. VCs never authorize resources |
| OWASP NHI Top 10 | Questionnaire categories, risk tier and findings, when the agent sends them |
| SPIFFE, SPIRE | Optional enrollment evidence; the identity stays the anchor key |
| Microsoft Entra federation | RS256 token with OIDC discovery and JWKS, deny-by-default subject mapping and exact audience allowlist in the production profile |
| SSF and CAEP | Agent revoked, suspended and host-changed events published; an account-disabled event accepted from your identity provider |
Oathera does not use DPoP: the operation proof plays that role for each tool call. Every signing key is Ed25519 except Entra federation tokens, which use RS256. The Oathera Identity Service signs with one active key (kid) at a time, and rotation keeps overlapping keys in the published JWKS.
Platforms and hosted demo
- Runtime. Node 24 or later.
- Host discovery. Linux, macOS and Windows; detects Docker, Kubernetes and Podman; reads AWS, GCP and Azure instance details.
- Protected core. Built for
linux-x64-gnuandlinux-arm64-gnu, and required by default. - Oathera Identity Service.
https://ais.oathera.org, with OIDC discovery and/jwks. Demo profile. - Simulator.
https://sim.oathera.org. - State. The hosted Oathera Identity Service keeps state in memory. It sleeps after one hour idle, and enrolled agents and keys then reset.
- Rollout stages. Watch first, enforce for a few agents, then enforce everywhere.
Developer data sheet and simulator
The developer data sheet covers keys, enrollment, the identity token, the operation proof, the checks and the standards on two pages.
Developer data sheet (PDF) Open the simulator Use cases
The simulator shows a stolen token sent as a bearer credential straight to the resource server, a replayed proof and a tampered call, each refused.