> ## Documentation Index
> Fetch the complete documentation index at: https://docs.truthlocks.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Verify Attestation
> Performs a full cryptographic and status verification of an attestation.
## Verdict Truth Table
| Verdict | Valid | Description |
|---------|-------|-------------|
| VALID | true | Signature correct, attestation active |
| REVOKED | false | Attestation explicitly revoked |
| SUPERSEDED | false | Replaced by newer attestation |
| ALTERED | false | Signature verification failed |
| UNKNOWN | false | Attestation not found |
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
The UUID of the attestation to verify. This is the unique identifier returned
when the attestation was originally minted.
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.
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:
| Reason | Verdict | Description |
| :------------------------- | :----------------------- | :------------------------------------------------------------------------------------------------------------------------------------------ |
| `document_hash_mismatch` | `ALTERED` | The provided hash does not match the stored document hash. The content has been modified since it was protected. |
| `document_hash_not_stored` | (continues verification) | The attestation was minted without a document hash, so the check cannot be performed. Verification continues with signature and log checks. |
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.
| Verdict | Description |
| ---------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `VALID` | Cryptographically valid and trusted |
| `ALTERED` | Document hash mismatch — the content has been modified |
| `REVOKED` | Explicitly revoked by the issuer |
| `SUPERSEDED` | A newer version of this attestation exists. Follow `superseded_by_attestation_id` in the response to find the replacement. |
| `EXPIRED` | The attestation has passed its validity period |
| `INVALID` | Cryptographic signature verification failed |
| `NOT_FOUND` | No attestation exists with the given ID |
| `UNKNOWN_ISSUER` | The issuer could not be resolved or is no longer trusted |
### 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:
```json theme={null}
{
"verdict": "SUPERSEDED",
"superseded_by_attestation_id": "880e8400-e29b-41d4-a716-446655440003",
"reasons": ["attestation_superseded"]
}
```
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](https://verify.truthlocks.com) provides unlimited free verification for end-users.
| Channel | Auth required | Metered | Rate limit |
| :----------------------------- | :------------ | :-------------------------------------------- | :-------------------------- |
| `POST /v1/verify` (API) | No | Yes — counted against the issuer's plan quota | Plan-dependent |
| verify.truthlocks.com (Portal) | No | No — free and unlimited | Fair-use rate limiting only |
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.
```json 402 — Quota exhausted theme={null}
{
"code": "BILLING_LIMIT",
"message": "API verification quota exhausted for the current billing cycle. Upgrade your plan or use the free consumer portal at verify.truthlocks.com.",
"http_status": 402
}
```
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}`
## OpenAPI
````yaml mint-openapi.yaml POST /v1/verify
openapi: 3.0.3
info:
title: Truthlocks API
description: >
Truthlocks is a universal verification infrastructure for documents,
credentials, and digital assets.
This specification defines the canonical API for interacting with Truthlocks
services.
## Base URLs
- **Production**: `https://api.truthlocks.com`
- **Sandbox**: `https://sandbox-api.truthlocks.com`
## Authentication
- **API Keys**: Use `X-API-Key` header for machine-to-machine operations
- **Bearer Tokens**: Use `Authorization: Bearer ` for user-initiated
operations
## Tenant Identity
In production, tenant identity is derived from the authenticated context
(API key or JWT).
The `X-Tenant-ID` header is ignored in production to prevent spoofing.
version: 1.0.0
contact:
name: Truthlocks Support
url: https://truthlocks.com/support
email: support@truthlocks.com
servers:
- url: https://api.truthlocks.com
description: Production API
- url: https://sandbox-api.truthlocks.com
description: Sandbox Environment
security:
- APIKey: []
tags:
- name: Authentication
description: API key and token management
- name: Issuers
description: Issuer registration and trust management
- name: Keys
description: Cryptographic key management for issuers
- name: Attestations
description: Attestation lifecycle (mint, revoke, supersede)
- name: Verification
description: Attestation verification and proof bundles
- name: Governance
description: Issuer governance workflows (admin only)
- name: Identity
description: Organization, user, and role management
- name: Audit
description: Audit event queries
- name: Platform
description: Platform administration (super admin only)
- name: Platform Review
description: Staff review workflows for issuer applications
- name: Tenant Console
description: Tenant profile and lifecycle endpoints
- name: Health
description: Service health and readiness endpoints
- name: Risk
description: Risk signal ingestion and fraud detection
- name: Risk Enforcement
description: Risk enforcement actions — block, challenge, quarantine, and configuration
- name: Billing
description: Billing, subscription, and addon management
- name: Machine Identity
description: >-
Machine Agent Identity Protocol (MAIP) — agent registration, sessions,
trust, witness, compliance, orchestration, and observability
externalDocs:
description: Transparency read-only API (separate service spec)
url: >-
https://github.com/truthlocks/truthlock/blob/main/docs/transparency/openapi.yaml
paths:
/v1/verify:
post:
tags:
- Verification
summary: Verify Attestation
description: |
Performs a full cryptographic and status verification of an attestation.
## Verdict Truth Table
| Verdict | Valid | Description |
|---------|-------|-------------|
| VALID | true | Signature correct, attestation active |
| REVOKED | false | Attestation explicitly revoked |
| SUPERSEDED | false | Replaced by newer attestation |
| ALTERED | false | Signature verification failed |
| UNKNOWN | false | Attestation not found |
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/VerifyRequest'
example:
attestation_id: 660e8400-e29b-41d4-a716-446655440001
payload_b64url: eyJzdWJqZWN0IjoiZGlkOnRydXRobG9jazoxMjMiLCJ2ZXJpZmllZCI6dHJ1ZX0
document_hash_hex: a1b2c3d4e5f6...
responses:
'200':
description: Verification result
content:
application/json:
schema:
$ref: '#/components/schemas/VerifyResponse'
examples:
valid:
summary: Valid attestation
value:
verdict: VALID
valid: true
details:
issuer_id: 550e8400-e29b-41d4-a716-446655440000
issuer_name: Acme University
log_index: 42
revoked:
summary: Revoked attestation
value:
verdict: REVOKED
valid: false
details:
revoked_at: '2026-01-13T15:00:00Z'
reason: Certificate holder no longer employed
security:
- APIKey: []
- {}
components:
schemas:
VerifyRequest:
type: object
required:
- attestation_id
properties:
attestation_id:
type: string
format: uuid
description: The unique identifier of the attestation to verify.
payload_b64url:
type: string
description: >
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:
type: string
description: >
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.
VerifyResponse:
type: object
properties:
verdict:
$ref: '#/components/schemas/Verdict'
valid:
type: boolean
details:
type: object
properties:
issuer_id:
type: string
format: uuid
issuer_name:
type: string
log_index:
type: integer
checked_at:
type: string
format: date-time
Verdict:
type: string
enum:
- VALID
- INVALID
- REVOKED
- ALTERED
- SUPERSEDED
- UNKNOWN
description: |
- **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
securitySchemes:
APIKey:
type: apiKey
in: header
name: X-API-Key
description: API key for machine-to-machine authentication
````