Verify a message

Check a signature block or an explicit key, message and signature. This POST only reads.

POST/v1/verify

Access: Public; API key optional
Client: Browser fetch supported

JSON body#

Name	Location	Meaning
`block`	JSON	Complete pasted signature block. Maximum 32768 characters.
`at`	JSON	Optional Unix seconds. Defaults to now. Use a trusted publication timestamp.
`key, message, signature`	JSON	Raw mode instead of block. Ed25519 uses hex, composite keys and signatures use base64. message is the exact UTF-8 text.
`platform, subject`	JSON	Optional pair in raw mode to check account ownership at the chosen time.

Request examples#

javascript

const headers = new Headers();
headers.set("Content-Type", "application/json");
const response = await fetch("https://veil.rip/v1/verify", {
  method: "POST",
  headers,
  credentials: "omit",
  body: JSON.stringify({ block })
});
const verdict = await response.json();

Try the request#

Signature block

Checking here sends the message to Veil. Use /verify for a check that stays in your browser.

Response#

HTTP 200application/json

valid is the overall verdict. signatureOk, identity, device, keyState, account and reason explain it. Block mode also returns the parsed block and the matching key when found.

Field	Type	Meaning
`valid`	`boolean`	Combined verdict for signature, key state and any requested account ownership. HTTP 200 also covers `valid=false`.
`signatureOk`	`boolean`	Whether the cryptographic signature verifies.
`identity`	`IdentityRef \| null`	Card associated with the key or named in the block, when known.
`device`	`string \| null`	Signing device, when identified.
`role`	`string \| null`	Signing role, when identified.
`keyState`	`KeyState \| null`	Key validity at the requested time.
`account`	`object \| null`	platform, subject, owned and reason when platform/subject were requested.
`reason`	`string \| null`	Null when valid. Otherwise bad_signature, unknown_key, not_yet_valid, revoked, key_banned, identity_banned, not_linked, pending_takeover, identity_erased or unknown_identity. These are verdict reasons, not HTTP error codes.
`key`	`string, optional`	Matching public key for block mode; omitted if no key matched.
`block`	`object, optional`	Parsed block with n, url, message, alg, lang, quoted and flattened.

Example response

Illustrative values. Read the current response from your request.

json

{
  "valid": false,
  "signatureOk": true,
  "identity": null,
  "device": null,
  "role": null,
  "keyState": null,
  "account": null,
  "reason": "unknown_key"
}

Expand a nested object for its fields. Types ending in null allow a null value; optional fields may be absent. Other fields are present in that object.

Identity reference IdentityRef

Field	Type	Meaning
`n`	`integer`	Permanent card number.
`url`	`string`	Permanent card URL.
`name`	`string`	Current display name.
`nameHidden`	`boolean`	Whether staff hide the name.

Key state at a time KeyState

Field	Type	Meaning
`at`	`integer`	Time checked, in Unix seconds.
`active`	`boolean`	Whether the key was active at that time.
`reason`	`string`	active, not_yet_valid or revoked.
`validFrom`	`string`	Publication time of the version that added it.
`validUntil`	`string \| null`	Publication time of revocation, or null.

Response headers#

Header	Value	Meaning
`Content-Type`	`application/json`	Use the declared media type before choosing a parser.
`Date`	`HTTP date`	Server time. Compare it with your clock when signing requests.
`Retry-After`	`integer seconds, on rate_limited or busy`	Wait at least this long before retrying. Other 429/503 codes do not necessarily include it.

What to verify#

This is the server’s verdict. To verify independently, check the card’s proof and verify the signature locally.

Usage notes#

block can be combined only with at. Send the key, message and signature form to include platform and subject. No request-signing headers are needed.
For a file or a release, the same path takes a signature with the file’s hashes or a checksum list: see Verify a file or a release.

Errors#

API errors return an error object. Use error.code for program logic; error.message is English text for people and can change. Response and error guide

HTTP	Code	Meaning and next step
400	`invalid_block`	The signature block cannot be parsed or names another directory. Paste the complete block with its message and use the directory it names.
400	`invalid_json`	The body is not a JSON object, contains duplicate keys or has trailing data. Send one valid JSON object with `Content-Type` application/json.
400	`invalid_parameter`	A path, query or body field is missing, malformed or outside its accepted range. Correct the field named in `error.message` before sending again.
413	`payload_too_large`	The request body exceeds this endpoint’s byte limit. Reduce the encoded body. API-key management accepts at most 8 KiB.

When using an optional API key

HTTP	Code	Meaning and next step
401	`invalid_api_key`	The bearer credential is malformed, unknown, expired or revoked. Use an active key. To use anonymous public access, remove `Authorization` entirely. Invalid credentials never fall back automatically.
403	`api_key_scope`	The API key lacks read or verify scope, or the endpoint does not accept bearer keys. Use the correct scope. Identity writes and key management still require a device signature.
403	`api_key_suspended`	This API key is suspended. Ask staff to restore it; another key cannot lift an account suspension.
403	`developer_suspended`	The owner’s API account is suspended or the owner card is unavailable. Check the owner account and any staff restriction. Creating another key does not bypass suspension.

Shared request errors

HTTP Code Meaning and next step

429

HTTP	Code	Meaning and next step
429	`rate_limited`	An anonymous, signed-request or API-key allowance was exceeded. Wait at least `Retry-After` seconds. Share a queue and retry budget across your workers.
500	`internal_error`	An unexpected server error occurred. Internal details are not returned. Retry reads with bounded backoff. Check write results before sending a new signed operation.
503	`busy`	The application has reached a temporary concurrency or database limit. Wait `Retry-After` seconds and retry with bounded backoff.

rate_limited

An anonymous, signed-request or API-key allowance was exceeded.

Wait at least Retry-After seconds. Share a queue and retry budget across your workers.

500

internal_error

An unexpected server error occurred. Internal details are not returned.

Retry reads with bounded backoff. Check write results before sending a new signed operation.

503

busy

The application has reached a temporary concurrency or database limit.

Wait Retry-After seconds and retry with bounded backoff.

Read this entry as JSON