Protocol overview · technical layer

The technical layer behind Authority Finality.

Authority Graph, Decision Map, taxonomy & metadata, runtime & state model, profile inventory, coverage matrix, and the 16 protocol-core principles. Each section links back to the JSON Schemas, OpenAPI, and conformance fixtures that ship in github.com/KYE-Protocol.

Graph-first · explainable by default

Every decision comes with a Decision Map.

KYE is graph-first because authority is relational. Every entity, delegation, capability, credential, policy, state, decision, and evidence object is a node; every authority relationship is a typed edge. The runtime traverses, projects, and explains — so an auditor, regulator, dispute panel, or developer can answer why without rebuilding the chain by hand.

Authority Graph

Who or what can act — for whom, using which capability, under which scope, in which state.

Trace delegation paths, identify risky authority chains, detect stale grants, and prove accountability. GET /v1/graph/authority-path.

Decision Map

Replayable graph of one decision.

Actor → principal → delegation → capability → authority → scope → state → policy → decision → audit → evidence. GET /v1/decisions/{id}/map.

Evidence Graph

Decision ↔ evidence linkage.

Every decision references the authority grants, capability manifests, payloads, audit events, and evidence packs that prove it. GET /v1/evidence-packs/{id}/graph.

Blast Radius Map

What breaks if this is compromised.

Show every capability, agent, payload, and decision affected by a compromised credential, capability, or entity — before you revoke. GET /v1/graph/blast-radius.

Compliance Map

Projection to framework controls.

Map every entity, authority, capability, decision, and evidence pack to EU AI Act, ISO 42001, SOC 2, DORA, NIS2 controls via KYE Compliance Mapping Rail. GET /v1/graph/compliance-map.

Knowledge graph projection

Storage substrate is your choice.

KYE objects project into Postgres, Neo4j, Neptune, Memgraph, TigerGraph, ArangoDB, or an RDF store — the protocol defines node + edge contracts, never the database.

Entities vs. evidence

KYE governs entities and the evidence they produce — never confuses one for the other.

KYE governs acting entities, principal entities, capability entities, and evidence artefacts. Payloads are evidence artefacts that bind signed requests to authority decisions and audit trails — they carry state but never authority.

ConceptRoleExamples
Acting entityWho or what is actingAI agent, service, user, autonomous workflow
Principal entityOn whose behalfOrganisation, business, natural person, deployer
Capability entityUsing which capabilitySkill, tool, MCP tool, function, connector, playbook, model_profile, payment_action
Resource entityActing on which resourceWallet, dataset, document, vehicle, vessel, shipment
Credential entityCarrying which proofVerifiable credential, attestation, key
Evidence artefactRecording the actPayload artefact, audit event, transparency receipt, evidence pack
DecisionAuthority resultpolicy_decision_id · allow / allow_with_constraints / require_approval / deny / quarantine

KYE Payload Trust Profile — payloads are signed, hashed, replay-resistant artefacts. The runtime verifies them, binds the resulting decision back to the artefact, and emits replayable audit evidence. See profile inventory →

KYE binds signed payloads to entity authority, capability state, policy decisions, and replayable audit evidence.

How it works

Three steps, every time. Identify. Authorize. Prove.

A KYE-governed action is the same shape whether the actor is a human pressing a button, a service account hitting an API, or an AI agent running a tool. That uniformity is the whole point.

1

Identify

Resolve who’s acting, on whose behalf, and what they’re acting against — using one URN format across every entity class.

actor principal subject resource delegation_id credential_id
2

Authorize

Run the request through the PDP (or the low-latency embedded ePDP, or a sector-specialised sPDP). Return a standard decision with reasons, obligations and stop conditions.

PDP variants. PDP — central decision point. ePDP — embedded library, in-process, < 1ms p99, ideal for hot paths. sPDP — sector PDP: a profile-aware variant that bakes in the constraints of a regulated rail (e.g. payments sPDP enforces PSD3 SCA obligations + amount caps + corridor whitelists before the policy bundle ever runs). Same wire contract, same evidence-pack output.

  • allow_with_constraints — your app proceeds. It MUST honour the obligations attached (e.g. audit.emit, redaction.required) and abort if a stop_condition fires before completion.
  • require_approval — your app pauses, queues a human or system approver, and re-asks the PDP after the approval is recorded. The original request keeps the same policy_decision_id.
  • deny — your app stops, surfaces the reason code (e.g. scope_attenuation_violation, credential_revoked) to the user, and emits an audit event. No retry without a new authority.
3

Prove

Append the action to the audit chain, emit signed signals to subscribers, and on demand export a signed proof bundle a regulator can verify with public keys alone.

audit append signal.publish webhook (signed) proof bundle transparency receipt
Decision Map · the chain that produced the verdict

Every decision comes with a map.

The runtime emits a signed Decision Map with every /v1/runtime/authorize response. The map shows which inputs led to the verdict — the principal, the delegation, the actor, the capability, the scope, the state, and the policy — bound to the audit-chain entry and the evidence pack. Verifiable offline with public keys alone.

Try the live version on the agent-backed purchasing simulator — change any input and watch the chain recompute.

KYE Signal Bus · runtime, not registry

Every authority change, delivered as a signed event.

A registry is passive. KYE Protocol is a runtime authority layer — when authority changes, downstream systems must know before the next request lands. The KYE Signal Bus emits signed, replayable events for every grant, revocation, state transition, decision, approval, recovery action and evidence-pack lifecycle. Subscribers verify with public keys alone, deduplicate by event id, and bind every signal back to the audit chain.

24 event families · 79 well-known types (nine highlighted below)

personEntitycreated · verified · state_changed · suspended · quarantined · revoked · recovered · tombstoned
verified_userAuthoritygranted · updated · limited · elevated · frozen · revoked · expired
shareDelegationcreated · activated · expired · disputed · revoked
extensionCapabilityregistered · version_published · validated · deprecated · quarantined · revoked · invocation_allowed · invocation_denied
balanceDecisioncreated · allowed · denied · requires_approval · requires_step_up · quarantined · replayed · replay_mismatch
credit_cardPayments & agent purchasingpayment_authority.granted / revoked · purchase_authority.allowed / denied / requires_approval · card_token.bound / unbound / frozen
keyRecovery & break-glassrecovery.requested / approved / rejected / completed · break_glass.granted / used / expired / revoked
verifiedEvidence & auditaudit.event_appended · integrity_check_passed / failed · evidence_pack.generated / signed / verified · decision_map.generated
workspace_premiumSelf-audit & conformanceself_audit.started / completed / failed · conformance.self_test_passed / failed · certification.issued / revoked

Canonical envelope · one shape across every event

Schema: https://kyeprotocol.com/schemas/signal.json. Signing covers the full envelope; subscribers verify with the publisher's published JWKS.

{
  "schema_version":  "kye.webhook.v1",
  "event_id":        "kye:event:01HX...",
  "event_type":      "kye.authority.revoked",
  "event_version":   "1.0",
  "occurred_at":     "2026-05-06T21:30:00Z",
  "tenant_id":       "tenant_acme",
  "correlation_id":  "kye:corr:agent_purchase_001",
  "causation_id":    "kye:event:01HX-prev...",
  "actor_entity_id":     "kye:entity:agent:shopping_agent_456",
  "principal_entity_id": "kye:entity:person:customer_123",
  "subject_ref":     "kye:authority:grant:purchase_001",
  "reason_code":     "principal_revoked_authority",
  "data": { "previous_state": "active", "new_state": "revoked",
            "affected_capabilities": ["kye:capability:payment_action:card_purchase"] },
  "audit_ref":     "kye:audit:event_001",
  "evidence_refs": ["kye:evidence-pack:authority_revocation_001"],
  "delivery":  { "idempotency_key": "kye:event:01HX...", "replayable": true },
  "signature": { "algorithm": "ed25519", "key_id": "kye:key:webhook_signing_001",
                 "signature": "..." }
}

Endpoints · subscribe, manage, replay

  • POST /v1/webhook-endpoints · GET · PATCH · DELETE — manage subscriber endpoints + filter expressions
  • POST /v1/webhook-endpoints/{id}:test · :rotate-secret — synthetic-event smoke test, signing-key rotation
  • GET /v1/webhook-deliveries · POST .../{id}:replay — delivery log + per-delivery replay
  • GET /v1/events · GET .../{id} · POST .../{id}:replay · GET /v1/event-types
  • POST /v1/signals · POST /v1/signals/subscribe · GET /v1/signals/replay · GET /v1/signals/{id} — KYE Signal Bus publisher side

Delivery guarantees

  • Signed — over the canonical envelope, with JWKS-based verification and no shared secrets. Conformance test vectors verified in CI; the signing construction itself is part of the patent track.
  • Idempotent — subscribers dedup by event_id; replays carry the same id.
  • Retried — exponential backoff under a publisher-configured budget; per-subscriber retry policy.
  • Dead-lettered — exhausted retries land in DLQ for operator-initiated replay.
  • Replayable — ≥ 24-hour replay window via /v1/signals/replay; subscribers refetch missed events without involving the publisher.
  • Audit-bound — every publish, delivery, and retry is recorded as an audit event linked via audit_ref + evidence_refs.
  • Three transports — HTTPS webhook (REQUIRED), SSE / WebSocket (OPTIONAL), Kafka-compatible topic (OPTIONAL).
  • SSF / CAEP boundary adapter — KYE event types translate to OpenID Shared Signals Framework + CAEP at trust-domain boundaries; lossless for the in-scope families.

What ships today

Envelope schema, every event-family schema, error / reason codes, delivery-receipt format, verifier SDK (TypeScript / Python / Go), reference Gateway webhook handler + retry loop + DLQ + replay endpoint, conformance test vectors. All Apache 2.0.

Worked example · agent-purchase revocation

A customer revokes their shopping-agent's payment authority. One signed kye.authority.revoked event fans out to five subscribers: bank freezes the agent card token; merchant platform blocks future agent purchases; agent runtime removes the payment_action.card_purchase capability; SIEM opens an alert linked to the audit-chain ref; audit pipeline emits kye.evidence_pack.generated for the regulator-facing pack. All five verify with the same public-key set; the regulator can replay the entire flow offline.

KYE-on-KYE · the engine governs itself

The KYE Reference Gateway uses its own primitives to govern itself.

Eat-your-own-dog-food is the credibility test for any authority infrastructure. The KYE Reference Gateway boots itself as a KYE tenant: registers a self-entity (kye:gateway:<trust-domain>:reference:01), the canonical operator-action capability catalogue (kye.gateway.key.rotate, profile.activate, capability.register, rate.set, audit.checkpoint, conformance.run, self_audit.run, cascade.replay, tenant.create, tenant.suspend), and a bootstrap-operator root grant. Every operator action against the running Gateway routes through POST /v1/runtime/authorize on the same engine, hits the same audit chain, and emits the same Decision Map + Evidence Pack any external decision produces.

keyKey rotationPOST /v1/keys:rotate goes through kye.gateway.key.rotate; response carries self_governed.decision_id, audit_event_id, evidence_pack_id.
verified_userSelf-audit runPOST /v1/self-audit:run enumerates open authorities, expired credentials, stale delegations, compromised entities, audit checkpoints, conformance pass-rate; emits a signed SelfAuditRunRecord per kye-self-audit-attestation-v1.
historyRun historyGET /v1/self-audit/runs · GET /v1/self-govern/registry — replayable audit of every self-governed action.
scienceTested in CI9 unit tests + 5 wiring integration tests pass on every commit. Ships in the v1.0 commercial-track KYE Reference Gateway.

Why this matters for procurement: a regulator can replay an external decision against the Gateway and replay the Gateway’s own key rotations using the same JWKS, the same evidence-pack format, the same audit-chain primitives. Misbehaving operators are bounded by the same scope + state-vector + cascade primitives that bound external agents.

Public proof of mechanism — three signed fixture artefacts (run record, engine health, audit-chain integrity) live at /trust-self-audit with a published JWKS and a 90-line verifier anyone can run in Node 18+.

State model · six dimensions

An entity isn’t one state. It’s a six-dimension state vector, all auditable.

Most systems collapse identity, authority and risk into one boolean. KYE Protocol keeps them separate so a single failure mode — expired credential, suspicious behaviour, lost key — changes the right dimension without nuking the rest.

Quick map: the state vector has 6 dimensions below (each transitions independently). The entity_state dimension — the lifecycle of the actor itself — takes 15 well-defined values (see the simulator below). The other five dimensions have smaller value sets shown on each card.

entity_state
Lifecycle of the actor itself.
  • provisional
  • active
  • suspended
  • quarantined
  • stopped
  • tombstoned
emits: entity.activated · entity.suspended · entity.stopped
authority_state
Whether this actor has any active authority right now.
  • none
  • scoped
  • elevated
  • break_glass
  • frozen
emits: authority.elevated · authority.frozen
delegation_state
Whether the chain of delegations behind this actor is intact.
  • active
  • parent_revoked
  • self_revoked
  • expired
  • scope_violated
emits: delegation.revoked (recursive)
credential_state
Verifiable credentials held by this actor.
  • none
  • valid
  • expired
  • revoked
  • signature_invalid
emits: credential.revoked · credential.expired
recovery_state
Whether this actor is mid-recovery, post-compromise, or healthy.
  • healthy
  • recovery_requested
  • recovery_decided
  • compromised
  • rotated
emits: recovery.decided · break_glass.granted
risk_state
Telemetry-derived risk posture — informs sPDP without changing identity.
  • nominal
  • elevated
  • watch
  • denylisted
emits: risk.elevated · risk.cleared

Each dimension cascades independently. Stop the entity? Authority freezes, delegations & capabilities revoke, credentials stay valid (so post-mortem keeps working), risk locks at last-known. The vocabulary is open and pinned in the conformance pack.

Lifecycle simulator

The entity_state dimension takes 15 well-defined values — and only legal transitions.

Click through them. Try an illegal move (the protocol blocks it). Stop, quarantine or revoke an entity and watch the cascade roll down to its delegations, payment authorities and resource grants.

Current state
status: —
Cascaded effects
    Signal log
      Profiles for every sector

      Banking, healthcare, custody — no rewrites required.

      50 v1.0 profiles structured in three tiers: Core (18) — every conformant Gateway implements all 18; Sector overlays (25) — adopt only those that match your sector; Operational (7) — multi-tenant + service primitives. Core handles ~90% of the contract; overlays add domain specialisation. The Core surface never shifts.

      Tier-1 evaluation path: 10 Core profiles to read end-to-end before deciding to pilot — kye-core-v1 · kye-gateway-v1 · kye-conformance-v1 · kye-payments-v1 · kye-credentials-v1 · kye-attestation-v1 · kye-signals-v1 · kye-transparency-v1 · kye-recovery-v1 · kye-capability-v1. Add the EU AI Act + Payments-EU + Payments-Card overlays for your jurisdiction. Everything else composes on top.
      Run the 41-fixture conformance pack: github.com/KYE-Protocol/examplesclone & run npm test
      Coverage

      One protocol. Every actor, every action, every state.

      KYE Protocol is deliberately scoped to the identity, authority, scope, state, and audit layer — not custody, not settlement, not a policy engine. That makes it horizontal across vendors and vertical across regulators.

      Horizontal — the whole ecosystem

      A single URN spans every entity class your stack already has.
      human business person team workload service_account api_client connector ai_agent model model_version tool mcp_tool workflow prompt capability wallet payment_authority credential attestation resource document dataset policy

      Vertical — the whole lifecycle

      Every governed phase of every entity, with controlled state transitions and replayable proof.
      discover register verify attest delegate scope authorize act audit replay approve attenuate suspend stop quarantine revoke break-glass recover rotate transfer archive tombstone
      SOC 2 ISO 27001 ISO 42001 PCI DSS PSD2/PSD3 DORA NIS2 EU AI Act NIST AI RMF NIST 800-207 NIST CSF GDPR FedRAMP
      Verticalised — sectoral profiles surface the controls auditors already ask for.
      Implementable protocol · not a whitepaper

      From authority to audit — backed by schemas, taxonomies, metadata, and a traversable graph.

      KYE Protocol has three layers. Runtime Governance — authority, state, decisions, policy, evidence, audit. Protocol Design — schemas, dictionaries, taxonomies, metadata, graph, profiles, registries, conformance. Developer Adoption — APIs and SDKs. The separation matters: what the protocol decides is independent from how it ships, which is independent from how you use it.

      Tier A · Runtime governance — what KYE decides

      1

      Authority-first

      KYE’s centre is not identity, it is authority. Every action answers who or what is acting, on behalf of whom, using which capability, under what authority, in what state, with what audit trail. KYEAuthorityGrant, KYEAuthorityScope, KYEDelegation, KYEActingOnBehalfOf, KYEAuthorityState, KYEAuthorityDecision, KYEAuthorityRevocation, KYEAuthorityEvidence.

      authority-grant.json · delegation.json · scope.json
      2

      State-first

      Authority is meaningless without state. Every authorize call composes entity_state, authority_state, delegation_state, credential_state, capability_state, payload_state, recovery_state, risk_state. KYE is state-aware authority infrastructure.

      state-composition.json · 6+ dimensions · 10 illegal compositions
      3

      Decision-first

      Runtime systems need an answer. POST /v1/runtime/authorize returns one of allow / allow_with_constraints / require_approval / require_step_up / require_human_review / require_recovery / quarantine / deny — with reason code, matched policies, obligations, evidence refs — in milliseconds.

      policy-decision.json · signed decision_id
      4

      Policy-bound

      Policy-bound, not policy-bloated. KYE defines binding schema, decision result, obligations, reason codes, the PEP/PDP flow — not a new policy language. Integrate with the engines you already run: Cerbos, OPA, AWS Cedar, custom enterprise PDPs, IAM, API gateways, agent runtimes.

      policy bundles (rego / cerbos / cedar) · policy-decision.json
      5

      Evidence-first

      KYE turns authority into evidence. Every decision produces validation results, audit events, transparency receipts, signals — all bound by a policy_decision_id and aggregable into a signed evidence_pack a regulator can verify with public keys alone.

      evidence-pack.json · KYE Compliance Mapping Rail
      6

      Audit-trail-first

      No authority without audit. No audit without evidence. Every material change produces an append-only, hash-linked, timestamped, reason-coded, actor-bound, policy-bound, decision-bound audit event — exportable, replayable, externally verifiable.

      audit-event.json · signal.json · transparency-receipt.json

      Tier B · Protocol design — how KYE classifies and ships

      7

      Schema-first

      Every entity, authority grant, delegation, scope, capability manifest, validation result, audit event, evidence pack, payload artefact, taxonomy term, metadata binding, and compliance mapping is a canonical JSON Schema 2020-12 with an absolute $id at kye-protocol.github.io/schemas. OpenAPI, SDKs, validators, docs, and conformance tests are derived from schemas — not hand-written.

      KYE-Protocol/schemas · 115 schemas · 129 validated examples
      8

      Dictionary-first

      Authority decisions need shared vocabulary, or every implementation invents different words for the same thing. KYE ships canonical dictionaries for entity types, all state dimensions, decisions, reason codes, capability kinds, side-effect levels, data classes, signal types, redaction fields, taxonomies.

      public/vocabulary/*.md · 19 dictionary files
      9

      Taxonomy-first

      Authority decisions depend on classification. KYE ships 16 canonical V1 taxonomies — entity_type, capability_type, action_type, resource_type, data_class, side_effect_level, risk_state, environment, decision, reason_code, evidence_type, compliance_framework, sector, jurisdiction, and the two state taxonomies. Versioned, status-bound, mappable to framework controls.

      taxonomy-term.json · taxonomies-v1.md · 16 taxonomies
      10

      Metadata-first

      Metadata is not decorative — it influences decisions. Every KYE object carries a normative metadata block: labels, classifications, ownership, lineage, compliance. Field values draw from registered taxonomies. The runtime exposes metadata to the policy layer as request.{actor,capability,resource,authority}.metadata.

      metadata-binding.json · KYEMetadataSchema · KYEMetadataPolicyRule
      11

      Graph-first

      Authority is relational. KYE maps every entity, delegation, capability, credential, policy, state, decision, and evidence object into a traversable Authority Graph. Every decision returns a Decision Map; compromise produces a Blast Radius Map; compliance projects to a Compliance Map. Storage substrate is implementation choice (Postgres, Neo4j, Neptune, Memgraph, TigerGraph, ArangoDB, RDF).

      graph-node.json · graph-edge.json · decision-map.json
      12

      Profile-first

      Core stays small. Domain extensions live in profiles — Capability, Recovery, Healthcare, Payments, Payload Trust, Taxonomy & Metadata, Graph, EU AI Act, ISO 42001, Defence, Energy, Manufacturing, and more. Profiles never modify Core; they add vocabulary, schemas, endpoints, and conformance fixtures. Adopt only what you need.

      kye-*-v1 profile specs · 58 v1.0 normative profiles
      13

      Registry-first

      Every object — entity, authority grant, delegation, capability, profile, dictionary, taxonomy, metadata schema, graph node / edge, policy, issuer, trust anchor, evidence pack, compliance mapping, webhook — is resolvable. The protocol defines registry semantics; deployments choose where to host.

      /.well-known/kye · /v1/{entities,delegations,capabilities,taxonomies,metadata-schemas,graph,…}
      14

      Conformance-first

      A protocol without conformance is marketing language. KYE publishes a black-box fixture pack that any conformant Gateway must pass — the same pack tests vendor stacks, internal stacks, and the reference Gateway, byte-for-byte the same.

      41 conformance fixtures · 41/41 pass · conformance-report.json normative

      Tier C · Developer adoption — how KYE reaches developers

      15

      API-first

      Validation happens at runtime. The headline endpoint POST /v1/runtime/authorize answers can this entity perform this action, on behalf of this principal, using this capability, under this scope, in this state? — in milliseconds, with a signed decision. Graph queries (authority path, delegation path, capability dependencies, blast radius) are first-class.

      193 OpenAPI operations · 87+ runtime endpoints · redocly-lint clean
      16

      SDK-first

      Developers should not implement protocol validation by hand. KYE ships TypeScript, Python, and Go SDKs with schema types, local validators, decision clients, signing/verification helpers, policy adapters, audit emitters, capability-manifest builders, evidence-pack helpers, taxonomy resolvers, metadata classifiers, graph traversal clients, decision-map renderers.

      KYE-Protocol/sdk-{typescript,python,go} · 67 + 51 + go-pass
      Where it sits in your stack

      MCP and OAuth solve parts. KYE solves the whole identity-authority-audit problem.

      MCP and A2A handle agent communication. OAuth and GNAP do human authorization. SPIFFE does workload identity. SCITT does transparency. KYE Protocol is the contract layer that composes them — one URN, one delegation chain, one decision vocabulary, one cascade, one audit chain.

      ↔ scroll horizontally to see all columns

      Ready to see your AI agents flagged?

      Start in shadow mode. We’ll deliver your first Evidence Pack in 4–8 weeks.