Skip to main content
Oathera logo Oathera
Use casesFive stories: no identity, a new identity, impersonation, cloning, and a call outside the boundary. PlatformOathera Agent Enrollment, the Oathera Identity Service and Oathera Agent Enforcement. FeaturesWhat Oathera does for you, grouped by purpose. IntegrationsYour identity provider, your MCP servers, your cloud. SecurityHow Oathera fails closed, and what it doesn't do.
Developer sectionComponents, the identity token, standards and settings. Data sheetsThe buyer and developer data sheets, as PDFs. LearnGuides on giving AI agents an identity of their own. GlossaryPrincipal, sponsor, anchor key, key digest, identity token. SimulatorWatch a stolen token, a replayed proof and a tampered call get refused.
About usThe team and the mission behind Oathera. BlogPosts from the Oathera team. ContactTalk to the founders, or become a design partner. LinkedIn ↗Oathera on LinkedIn.
Privacy PolicyHow we handle data. Terms of ServiceTerms for using Oathera. Data Processing AgreementOur DPA for customers. Sub-processorsThird parties we rely on.
Become a design partner

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.

On this page

  1. Components
  2. Put Oathera beside an agent
  3. Oathera Agent Enforcement
  4. Enrollment
  5. Host digest and host binding
  6. The identity token
  7. The operation proof
  8. Boundary decision and gateway assertion
  9. Lifetimes and revocation
  10. Settings
  11. Standards
  12. Platforms and hosted demo
  13. Developer data sheet and simulator

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 /mcp when IDENTITY_MCP_PORT is set, with workload authentication set by IDENTITY_MCP_AUTH_MODE (default bearer). 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 (default json).
  • Protected core. Both MCPs load the native oathera-core only 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=false allows 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.

Tools. The bundle's sample resource server has three tools to try it with: list_reports, read_report and create_report. Oathera Agent Enforcement verifies proofs for any tool you configure, and an operation Oathera Agent Enrollment doesn't know is refused invalid_operation. Ask us for the MCP bundle.

Oathera Agent Enforcement

  • In-process. attachOatheraGateway attaches to a Node MCP SDK server; the demo Oathera Agent Enforcement uses it.
  • Proxy. createOatheraGatewayProxy sits in front of a stdio or Streamable HTTP MCP server written in any language.
  • Schema. Enforced tools gain identity_token and proof fields in their input schema.
  • Audit. Every enforced call writes one boundary_decision event; every unenforced call writes one gateway_unenforced_call event.
  • Default deny. With GATEWAY_DEFAULT_DENY=true, a tool with no enforcement entry is refused operation_not_configured. Default false outside 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 refused unknown_tool.
  • Argument allow-lists. Arguments outside a tool's allow-list are refused.
  • No identity token. A call without one is refused invalid_token locally, 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

  1. On start, Oathera Agent Enrollment's key provider creates an Ed25519 anchor key: a software key in a .keys directory next to IDENTITY_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.
  2. enroll asks the agent for its attributes through an MCP form: agent type, capabilities, model, OS, version, AI providers and AI models.
  3. 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_attributes on a malformed block.
  4. It observes the host and computes the host digest.
  5. POST /enroll/start carries 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.
  6. 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.
  7. 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.
  8. 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_CLEARANCE 0, 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 answers 403 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 DMI product_uuid. macOS reads IOPlatformUUID. Windows reads MachineGuid.
  • 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=off reports none.
  • HOST_BINDING. off skips 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. enforce refuses with 403 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 when AWS_IDENTITY_CERT_PEM is 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.

ClaimMeaning
iss, sub, jti, iat, nbf, expIssuer, agent ID, token ID, times
audThe single audience the token is for. It must be requested and on the agent's allowlist, and the Oathera Identity Service checks it
tenant_idThe tenant
cnf (cnf.jwk)The session public key (RFC 7800)
anchor_jkt, key_epoch, revocation_epochThe anchor key digest and the epochs the token was issued under
principalThe person who approved the agent
capabilitiesWhat the agent may do; a capability can be privileged
task_policy, assuranceThe task policy and the assurance of the evidence behind the token
agent_label, platformFrom the enrollment record
Risk tierFrom the NHI attributes, when sent
Host postureTruncated host digest, host confidence, host_attested, findings count, drift
Enrollment attribute blockSponsor, operational boundary and tier (the requested clearance)
clearanceThe granted clearance, never more than the evidence supports

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 cnf key, 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 unless IDENTITY_MCP_SIGN_REQUEST_ALLOWLIST pins 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; aud when 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 resources list. 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_STORE set to redis, valkey or durable, or an injected store) covers several.

Lifetimes and revocation

LifetimeWhat
For the agent's life on a hostAnchor 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 privilegedSession key, identity token with its granted clearance, host comparison
Per callOperation 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 /agents page: raises its revocation epoch and marks it revoked. Its next token request and next boundary decision are refused. Tokens already issued stay valid until exp; 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

SettingWhereDefault
HOST_BINDINGOathera Identity Servicewarn (also off, enforce)
HOST_REQUIRE_ATTESTATIONOathera Identity Serviceoff
AGENT_TOKEN_LIFETIMEOathera Identity Service120 s (the v1 token only)
CREDENTIAL_FORMATOathera Identity Servicejson (or vc)
AIS_APPROVED_GATEWAYSOathera Identity Service
TRUSTED_SPIFFE_DOMAINSOathera Identity Serviceunset
ADMIN_AUTH_MODEOathera Identity Servicenone
IDENTITY_MCP_REQUESTED_CLEARANCEOathera Agent Enrollment0
HOST_DISCOVERY_LEVEL, _PII, _SALT, HOST_CLOUD_PROBEOathera Agent Enrollment
IDENTITY_STATE_PATH, AIS_URLOathera Agent EnrollmentHosted Oathera Identity Service in the bundle
GATEWAY_AIS_DECISION_URLOathera Agent EnforcementSet in the demo profile
GATEWAY_DEFAULT_DENYOathera Agent Enforcementfalse outside production
OATHERA_CORE_REQUIREDBoth MCPsrequired
OATHERA_TELEMETRYBoth MCPsoff
REPLAY_STOREOathera Agent Enforcementprocess-local (also redis, valkey, durable)
OATHERA_PROFILEAlldemo in every hosted service

Product settings use the OATHERA_ prefix; the legacy prefix is still read, with a one-time deprecation log.

Standards

StandardHow Oathera uses it
JWT, JWS, EdDSAEvery 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 headerProof of key possession on Oathera's HTTP calls. The header is an Oathera profile aligned toward draft-hardt-httpbis-signature-key
OIDC with PKCEThe principal signs in at your IdP (OIDC_ISSUER); the hosted demo uses an internal demo IdP
W3C VC 1.1, Ed25519Signature2020Agent, sponsor and operational-boundary credentials with suspend, reinstate and revoke, when CREDENTIAL_FORMAT=vc. VCs never authorize resources
OWASP NHI Top 10Questionnaire categories, risk tier and findings, when the agent sends them
SPIFFE, SPIREOptional enrollment evidence; the identity stays the anchor key
Microsoft Entra federationRS256 token with OIDC discovery and JWKS, deny-by-default subject mapping and exact audience allowlist in the production profile
SSF and CAEPAgent 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-gnu and linux-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.

← Back to Oathera
Oathera logo Oathera

Every AI agent, sworn in. Oathera gives every AI agent an identity bound to the machine it runs on, with a named person who answers for it, and checked every time it acts.

Product

  • Use cases
  • Platform
  • Features
  • Integrations
  • Security

Developers

  • Developer section
  • Data sheets
  • Learn
  • Glossary
  • Simulator

Company

  • About us
  • Blog
  • Contact
  • GitHub

Legal

  • Privacy Policy
  • Terms of Service
  • Data Processing Agreement
  • Sub-processors
© 2026 Oathera Inc. · All rights reserved
Know Your Agent (KYA)

Cookie preferences

We use cookies to run this site and, with your consent, to understand usage and improve Oathera. Strictly necessary cookies are always on; you can choose whether to allow analytics and marketing cookies below.

  • Strictly necessaryAlways on

    Required for the site to work, including security, load balancing, and remembering your cookie choices. These cannot be switched off.

  • Help us measure traffic and see how the site is used, so we can improve it. No personal profiles are built.

  • Used to make messages about Oathera more relevant across other sites. Off unless you turn it on.