Skip to main content
POST
/
v1
/
verify
Verify Attestation
curl --request POST \
  --url https://api.truthlocks.com/v1/verify \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "attestation_id": "660e8400-e29b-41d4-a716-446655440001",
  "payload_b64url": "eyJzdWJqZWN0IjoiZGlkOnRydXRobG9jazoxMjMiLCJ2ZXJpZmllZCI6dHJ1ZX0",
  "document_hash_hex": "a1b2c3d4e5f6..."
}
'
{
  "verdict": "VALID",
  "valid": true,
  "details": {
    "issuer_id": "550e8400-e29b-41d4-a716-446655440000",
    "issuer_name": "Acme University",
    "log_index": 42
  }
}
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

​
attestation_id
string
required
The UUID of the attestation to verify. This is the unique identifier returned when the attestation was originally minted.
​
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.

​
Verdict Reference

Every verification request returns exactly one verdict value.
VerdictDescription
VALIDCryptographically valid and trusted
ALTEREDDocument hash mismatch — the content has been modified
REVOKEDExplicitly revoked by the issuer
SUPERSEDEDA newer version of this attestation exists
EXPIREDThe attestation has passed its validity period
INVALIDCryptographic signature verification failed
NOT_FOUNDNo attestation exists with the given ID
UNKNOWN_ISSUERThe issuer could not be resolved or is no longer trusted

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