verify document
verify_documentVerify a certificate or evidence bundle was issued by the platform and not altered by re-deriving its HMAC signature, enabling trust in third-party documents.
Instructions
Verify that a downloaded certificate or evidence bundle was issued by the platform and has not been altered, by re-deriving its HMAC signature — use it when a third party hands you a document and you need to trust its numbers. POST /v1/verify (API-key scope: read). Returns: Always 200 for a well-formed body: { ok: true, key_id: string } when the bytes are ours and unaltered; otherwise { ok: false, reason: 'unsigned' (no signature field) | 'malformed' (not an object or signature shape wrong) | 'unknown_key' (signed by a key this platform doesn't hold, e.g. after rotation) | 'mismatch' (any field was edited) | 'no_secret' (verification not configured on the platform) }. Notes: Read scope suffices (POST that writes nothing); nothing is stored. Verification canonicalises the document (keys sorted recursively, undefined dropped) before hashing, so key order does not matter but any value change does. Sent with Cache-Control: no-store.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| document | Yes | The full signed JSON document exactly as downloaded (a certificate or evidence bundle carrying signature: { alg: 'HS256', key_id, value }). The `document` key must be present (400 'Body must be { document: <signed JSON> }' otherwise); its value may be any JSON. |