Examples

The shape of KYE™ artefacts, in JSON.

These are illustrative payloads from KYE-Protocol/examples. They show the shape of KYE™ artefacts using public vocabulary; they are not normative and do not implement any KYE™ mechanism.

Purpose Permission API

Demo data

You learn: What the purpose-permission endpoints take and return. You can: Pick a request and send it.

Clinical lead · Issue the grant

Request
POST /purpose-permissions

{
  "grantee": "<grantee>",
  "purpose": "<purpose>",
  "scope": "<scope>",
  "ttl_days": 90
}
Response 201
{
  "grantee": "kye:ent:halden.example:agent:clin-03",
  "id": "kye:purpose:halden:clin-03:clinical-summarise-2026q4",
  "issued_by": "kye:ent:halden.example:officer:clinical-lead",
  "not_after": "2027-01-01T00:00:00Z",
  "not_before": "2026-10-01T00:00:00Z",
  "principal": "kye:ent:halden.example",
  "purpose": {
    "id": "kye:purpose-class:clinical.summarise",
    "label": "Summarise care records for the treating clinician"
  },
  "restrictions": {
    "dual_control": false,
    "jurisdiction": [
      "GB"
    ],
    "rate_cap": {
      "requests_per_minute": 20
    },
    "requires_evidence": true
  },
  "scope": {
    "actions": [
      "read",
      "summarise"
    ],
    "data_classes": [
      "health.record"
    ],
    "resources": [
      "kye:res:halden.example:ehr:ward-7"
    ]
  },
  "version": 1
}
How this widget is built
Demonstrates
App API
Components
  • /api/v1/purpose-permissions
  • OpenAPI contract (app.yaml)
Flow
Requests come from the app API contract; the issue response is the demo grant. Architecture diagram
Used on
  • /examples/: On the examples page, with the rest of its scenario.
  • /sandbox/demos/demo/: The sandbox demo: the same calls, answered from the contract.
  • /lab/: The lab: call the API in your browser.

delegation.json

{
  "delegation_id": "kye:del:acme.example:01JYABC0000000000000000000",
  "actor_entity_id": "kye:ent:acme.example:ai_agent:01JY3J1D4E5A7K3JQFK4E0Q1XZ",
  "subject_entity_id": "kye:ent:acme.example:business:01JYACME000000000000000000",
  "delegator_entity_id": "kye:ent:acme.example:person:01JYCFO0000000000000000000",
  "basis": "explicit_delegation",
  "allowed_actions": [
    "document.render",
    "document.read"
  ],
  "forbidden_actions": [
    "document.export"
  ],
  "scope": {
    "scope_id": "kye:scp:acme.example:01JYFINANCE000000000000000",
    "constraints": {
      "workspace": "finance",
      "environment": "prod",
      "jurisdiction": "GB",
      "data_constraints": {
        "redaction_required": true,
        "external_send_allowed": false
      },
      "obligations": ["audit.emit"]
    }
  },
  "status": "active",
  "valid_from": "2026-04-01T00:00:00Z",
  "valid_until": "2026-12-31T23:59:59Z"
}

entity.json

{
  "entity_id": "kye:ent:acme.example:ai_agent:01JY3J1D4E5A7K3JQFK4E0Q1XZ",
  "trust_domain_id": "kye:td:acme.example",
  "entity_type": "ai_agent",
  "display_name": "Acme Procurement Agent",
  "status": "active",
  "lifecycle_state": "active",
  "immutable": {
    "root_entity_id": "kye:ent:acme.example:ai_agent:01JY3J1D4E5A7K3JQFK4E0Q1XZ",
    "registration_event_id": "kye:aud:acme.example:01JY3J1D4E5A7K3JQFK4E0Q1XZ",
    "root_hash": "sha256:8f9c2b1a4d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a",
    "initial_entity_type": "ai_agent"
  },
  "classification": {
    "risk_level": "medium",
    "sector_tags": ["finance"],
    "data_classes": ["internal", "financial_data"]
  },
  "labels": {
    "team": "finance-ops",
    "environment": "prod"
  },
  "created_at": "2026-04-01T10:00:00Z",
  "updated_at": "2026-04-15T12:30:00Z"
}

policy-decision.json

{
  "policy_decision_id": "kye:pdc:acme.example:01JYPDC0000000000000000000",
  "decision": "allow_with_constraints",
  "reasons": [
    "actor_active",
    "delegation_valid",
    "scope_match"
  ],
  "obligations": [
    "audit.emit",
    "redaction.required"
  ],
  "stop_conditions": [
    "delegation_revoked"
  ],
  "created_at": "2026-04-15T12:30:00Z"
}

runtime-event.json

{
  "runtime_event_id": "kye:rte:acme.example:01JYRTE0000000000000000000",
  "actor_entity_id": "kye:ent:acme.example:ai_agent:01JY3J1D4E5A7K3JQFK4E0Q1XZ",
  "acting_on_behalf_of_entity_id": "kye:ent:acme.example:business:01JYACME000000000000000000",
  "resource_entity_id": "kye:ent:acme.example:document:01JYDOC0000000000000000000",
  "action": "document.render",
  "delegation_id": "kye:del:acme.example:01JYABC0000000000000000000",
  "policy_decision_id": "kye:pdc:acme.example:01JYPDC0000000000000000000",
  "outcome": "executed",
  "occurred_at": "2026-04-15T12:30:01Z",
  "recorded_at": "2026-04-15T12:30:01Z"
}

scope.json

{
  "scope_id": "kye:scp:acme.example:01JYFINANCE000000000000000",
  "actions": [
    "document.read",
    "document.render"
  ],
  "constraints": {
    "workspace": "finance",
    "environment": "prod",
    "jurisdiction": "GB",
    "limits": {
      "max_calls_per_day": 500
    },
    "data_constraints": {
      "allowed_data_classes": ["internal", "financial_data"],
      "redaction_required": true,
      "external_send_allowed": false
    },
    "obligations": [
      "audit.emit",
      "monitor.realtime"
    ]
  }
}