{"schema_version":"kai-verify-1","endpoint":"POST /api/kaios/verify","discovery":"GET /api/kaios/verify","auth":{"scheme":"Ed25519 public-key signature","env_var":"KAIOS_ISSUER_PUBLIC_KEY","notes":"When KAIOS_ISSUER_PUBLIC_KEY is unset the endpoint returns 503 \"Verification disabled\". When set, the server verifies the signature on every request; mismatches return 401."},"issuer_public_key":{"format":"PEM SPKI","example":"-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VwAyEADvVAaT5NPG9OejnSFQlReOZQJcrykKoSAK3k+S7aJO0=\n-----END PUBLIC KEY-----","env_var":"KAIOS_ISSUER_PUBLIC_KEY","test_only":true,"test_only_warning":"TEST ONLY: This public key and signature are an isolated example fixture. Configure KAIOS_ISSUER_PUBLIC_KEY with this key only in a local/test verifier; do not use it for production receipts."},"canonicalization":{"rule":"The verifier does not canonicalize payload_string; it verifies the supplied UTF-8 bytes as-is.","algorithm":"The issuer chooses how to serialize `payload` into `payload_string`, signs those exact UTF-8 bytes with Ed25519, and encodes the 64-byte signature as 128 hexadecimal characters. The verifier parses the signed JSON and requires its value to equal `payload`, ignoring object key order. Invalid JSON or a mismatch returns 400."},"content_type":"application/json","required_fields":{"signature":{"type":"string (hex)","description":"Ed25519 signature over `payload_string`, decoded from hex. Exactly 128 hex chars (64 bytes); Node hex encoding produces lowercase characters."},"payload_string":{"type":"string","description":"A non-empty string whose exact UTF-8 bytes are verified as supplied. It must contain valid JSON whose parsed value equals `payload`; invalid JSON or a mismatch returns 400."},"payload":{"type":"object","description":"Structured form of the receipt. Required fields inside: non-empty `issuer` string, valid ISO-8601 `issued_at` timestamp, and object-valued `disclosed_fields` (not null or an array). It must equal the parsed JSON in `payload_string`; `ciphertext_bundle` is optional in the response but must also match when present."}},"responses":{"200":{"ok":true,"valid":true,"issuer":"string","issued_at":"ISO-8601 string","disclosed_fields":"object"},"400":{"ok":false,"errors":["string"]},"401":{"ok":false,"error":"Invalid signature"},"503":{"ok":false,"error":"Verification disabled: KAIOS_ISSUER_PUBLIC_KEY not configured"}},"example_response":{"ok":true,"valid":true,"issuer":"kaios.automa8.ai","issued_at":"2026-07-24T12:00:00Z","disclosed_fields":{"task":"undercollateralized-lending","loan_size_usd":75000}},"response_fields":{"ok":"True when the verification request completes successfully.","valid":"True when the signature verifies over the exact UTF-8 bytes in payload_string and its parsed JSON equals payload.","issuer":"Copied from the structured request payload.issuer.","issued_at":"Copied from the structured request payload.issued_at.","disclosed_fields":"Copied from the structured request payload.disclosed_fields."},"example_envelope":{"signature":"a2a840955190e68e1801646322b7abfdd54fb70b30ac9e23a4d1d777331e3225b20abee94c6e6846718cfe4f846ee16b51e450ae6fc7f9189004fcb4de74da01","payload_string":"{\"issuer\":\"kaios.automa8.ai\",\"issued_at\":\"2026-07-24T12:00:00Z\",\"disclosed_fields\":{\"task\":\"undercollateralized-lending\",\"loan_size_usd\":75000}}","payload":{"issuer":"kaios.automa8.ai","issued_at":"2026-07-24T12:00:00Z","disclosed_fields":{"task":"undercollateralized-lending","loan_size_usd":75000}}}}