Skip to main content
POST
Verify Attestation
Performs a comprehensive multi-step verification of an attestation. The pipeline resolves the attestation, checks document integrity, validates status (revoked, superseded, expired), resolves issuer governance metadata, verifies the cryptographic signature against the issuer’s public key, checks the transparency log inclusion proof, and evaluates platform policies. Returns a single verdict with detailed reasons, transparency log data, and full issuer governance context including both current and snapshot-at-mint values. This endpoint is publicly accessible and does not require authentication.

Parameters

string
required
The UUID of the attestation to verify. This is the unique identifier returned when the attestation was originally minted.
string
Base64url-encoded payload for signature verification. If provided, the system verifies that the SHA-256 hash of this payload matches the stored payload_hash. Use this to confirm you hold the exact original content that was attested.
string
SHA-256 hex hash of the original document for integrity verification. If provided, compared against the stored document_hash. Use this when you want to verify a file’s integrity without sending the full payload over the wire. The comparison is case-insensitive.

Document hash verification

When you include document_hash_hex in your verification request, the platform compares it against the document_hash stored at mint time. Two additional reason codes may appear in the reasons array of the response:
The document_hash is set automatically during minting. The platform resolves it from three sources in priority order: an embedded claims.document.sha256 in the payload, an explicit document_hash field in the mint request, or an auto-computed SHA-256 of the payload bytes.

Verdict reference

Every verification request returns exactly one verdict value.

Superseded attestations

When an attestation has been replaced by a newer version, the verdict is SUPERSEDED and the response includes a superseded_by_attestation_id field pointing to the replacement. Use this to follow the version chain:
To verify the latest version, make a second request using the superseded_by_attestation_id value as the attestation_id.

Billing and rate limits

API verification requests are metered against your organization’s billing plan. The consumer portal at verify.truthlocks.com provides unlimited free verification for end-users.
When the issuer’s API verification quota is exhausted, the endpoint returns HTTP 402 with the BILLING_LIMIT error code. Upgrade your plan or wait for the quota to reset at the start of the next billing cycle.
402 — Quota exhausted
For most use cases, share a verification link instead of calling the API directly. Portal verifications are free and provide a rich UI with issuer branding, governance details, and document integrity checks.Verification link format: https://verify.truthlocks.com/a/{attestation_id}

Authorizations

X-API-Key
string
header
required

API key for machine-to-machine authentication

Body

application/json
attestation_id
string<uuid>
required

The unique identifier of the attestation to verify.

payload_b64url
string

Base64url-encoded payload for signature verification. If provided, the system verifies that the SHA-256 hash of this payload matches the stored payload_hash. Use this to confirm you hold the exact original content that was attested.

document_hash_hex
string

SHA-256 hex hash of the original document for integrity verification. If provided, compared against the stored document_hash. Use this when you want to verify a file's integrity without sending the full payload over the wire.

Response

200 - application/json

Verification result

verdict
enum<string>
  • VALID: Signature verified and attestation is active
  • REVOKED: Attestation was explicitly revoked
  • SUPERSEDED: Attestation replaced by a newer version
  • ALTERED: Signature verification failed (tampered)
  • INVALID: General validation failure
  • UNKNOWN: Attestation not found
Available options:
VALID,
INVALID,
REVOKED,
ALTERED,
SUPERSEDED,
UNKNOWN
valid
boolean
details
object