Verify Attestation

POSThttps://sandbox-api.truthlocks.com/v1/verify

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.

Body Parameters

attestation_idstringrequired

The UUID of the attestation to verify. This is the unique identifier returned when the attestation was originally minted.

Defaults to 660e8400-e29b-41d4-a716-446655440001

payload_b64urlstring

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_hexstring

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.

Responses

{
  "verdict": "VALID",
  "reasons": [
    "signature_ok",
    "status_current",
    "transparency_proof_ok",
    "governance_ok"
  ],
  "attestation_id": "660e8400-e29b-41d4-a716-446655440001",
  "issuer_id": "550e8400-e29b-41d4-a716-446655440000",
  "kid": "ed-key-1",
  "alg": "Ed25519",
  "payload_hash": "dGhpc19pc19hX3NhbXBsZV9oYXNo",
  "document_hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
  "log": {
    "log_id": "truthlock-prod-log-v1",
    "leaf_index": 1056,
    "proof_checked": true
  },
  "governance": {
    "issuer_status": "ACTIVE",
    "issuer_trust_tier": "VERIFIED",
    "issuer_risk_rating": "LOW",
    "issuer_jurisdiction": "US",
    "issuer_display_name": "Acme University",
    "primary_color": "#1e40af",
    "accent_color": "#3b82f6",
    "logo_url": "https://cdn.truthlocks.com/logos/acme-university.png",
    "snapshot_status": "ACTIVE",
    "snapshot_trust_tier": "VERIFIED",
    "snapshot_risk_rating": "LOW",
    "snapshot_jurisdiction": "US"
  }
}

{
  "verdict": "ALTERED",
  "reasons": [
    "document_hash_mismatch"
  ],
  "attestation_id": "660e8400-e29b-41d4-a716-446655440001",
  "issuer_id": "550e8400-e29b-41d4-a716-446655440000",
  "kid": "ed-key-1",
  "alg": "Ed25519",
  "payload_hash": "dGhpc19pc19hX3NhbXBsZV9oYXNo",
  "document_hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
  "log": {
    "log_id": "truthlock-prod-log-v1",
    "leaf_index": 1056,
    "proof_checked": false
  },
  "governance": {
    "issuer_status": "ACTIVE",
    "issuer_trust_tier": "VERIFIED",
    "issuer_risk_rating": "LOW",
    "issuer_jurisdiction": "US",
    "issuer_display_name": "Acme University",
    "primary_color": "#1e40af",
    "accent_color": "#3b82f6",
    "logo_url": "https://cdn.truthlocks.com/logos/acme-university.png",
    "snapshot_status": "ACTIVE",
    "snapshot_trust_tier": "VERIFIED",
    "snapshot_risk_rating": "LOW",
    "snapshot_jurisdiction": "US"
  }
}

{
  "verdict": "REVOKED",
  "reasons": [
    "attestation_revoked"
  ],
  "attestation_id": "660e8400-e29b-41d4-a716-446655440001",
  "issuer_id": "550e8400-e29b-41d4-a716-446655440000",
  "kid": "ed-key-1",
  "alg": "Ed25519",
  "payload_hash": "dGhpc19pc19hX3NhbXBsZV9oYXNo",
  "document_hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
  "log": {
    "log_id": "truthlock-prod-log-v1",
    "leaf_index": 1056,
    "proof_checked": false
  },
  "governance": {
    "issuer_status": "ACTIVE",
    "issuer_trust_tier": "VERIFIED",
    "issuer_risk_rating": "LOW",
    "issuer_jurisdiction": "US",
    "issuer_display_name": "Acme University",
    "primary_color": "#1e40af",
    "accent_color": "#3b82f6",
    "logo_url": "https://cdn.truthlocks.com/logos/acme-university.png",
    "snapshot_status": "ACTIVE",
    "snapshot_trust_tier": "VERIFIED",
    "snapshot_risk_rating": "LOW",
    "snapshot_jurisdiction": "US"
  }
}

{
  "verdict": "NOT_FOUND",
  "reasons": [
    "attestation_not_found"
  ],
  "attestation_id": "99999999-0000-0000-0000-000000000000",
  "issuer_id": "",
  "kid": "",
  "alg": "",
  "payload_hash": "",
  "document_hash": "",
  "log": null,
  "governance": null
}

Verdict Reference

Every verification request returns exactly one verdict value. The verdict represents the final outcome of the multi-step verification pipeline. All verdicts are returned with HTTP 200 — use the verdict field, not the HTTP status code, to determine the result.

Verdict	Description	When It Occurs
VALID	The attestation is cryptographically valid, the issuer is trusted, and no revocation or expiry has occurred.	Signature verifies, issuer is active, status is current, transparency proof checks out.
ALTERED	The payload or document hash does not match the original signed content.	The provided payload_b64url or document_hash_hex does not match the stored hash.
REVOKED	The attestation was explicitly revoked by the issuing organization.	The issuer called the revoke endpoint, setting the attestation status to REVOKED.
SUPERSEDED	A newer version of this attestation has been issued, replacing this one.	The issuer minted a new attestation that supersedes this one via the supersede endpoint.
EXPIRED	The attestation has passed its expiration date and is no longer considered current.	The attestation had an expiry_at timestamp that is now in the past.
UNKNOWN_ISSUER	The issuer ID in the attestation is not registered in the trust registry.	The issuer_id does not match any known issuer, or the issuer has been removed from the registry.
NOT_FOUND	No attestation exists with the given ID.	The attestation_id does not match any record in the system.
INVALID	The cryptographic signature verification failed. The attestation data may have been tampered with.	The Ed25519 or ECDSA signature does not verify against the issuer's public key and the stored payload hash.

Verification Flow

When you call POST /v1/verify, the platform executes an 8-step verification pipeline. Each step can short-circuit with a verdict if a check fails. Only if all steps pass does the final verdict resolve to VALID.

Verification Pipeline

Resolve Attestation

Look up the attestation by ID in the trust registry. If not found, return NOT_FOUND immediately.

Document Hash Check

If document_hash_hex is provided, compare it against the stored document hash. A mismatch returns ALTERED.

Status Check

Check the attestation status for REVOKED, SUPERSEDED, or EXPIRED. If any apply, return the corresponding verdict.

Governance Lookup

Resolve the issuer's governance metadata: trust tier, risk rating, jurisdiction, display name, branding colors, and logo. Both current and snapshot-at-mint values are returned.

Key Resolution

Retrieve the issuer's public key by kid. If the key is compromised or rotated, flag accordingly. If the issuer is unknown, return UNKNOWN_ISSUER.

Signature Verification

Verify the Ed25519 or ECDSA signature against the issuer's public key and the stored payload hash. Failure returns INVALID.

Transparency Proof

Verify the attestation's inclusion in the transparency log by checking the Merkle proof against the log root. Records log_id, leaf_index, and proof status.

Policy Evaluation

Apply platform-wide and issuer-specific policies. If all checks pass, return VALID with the full verification report.

Short-circuit behavior: The pipeline stops at the first failing step and returns its verdict immediately. For example, if the attestation is revoked (step 3), steps 4-8 are skipped and the response returns REVOKED. This means the reasons array only contains codes for checks that were actually executed.

Governance Metadata

The governance object in the verification response provides rich context about the issuer. It contains both current values (the issuer's state right now) and snapshot values (the issuer's state when the attestation was originally minted).

Snapshot vs Current: An issuer's trust tier or risk rating may change over time. The snapshot fields let verifiers see the issuer's standing at the moment of minting, while the current fields reflect the issuer's live status. For maximum security, check both — a downgrade from VERIFIED to BASIC between mint time and now may warrant additional scrutiny.

Governance Object Fields

Field	Type	Description
`issuer_status`	string	Current status of the issuer (ACTIVE, SUSPENDED, REVOKED)
`issuer_trust_tier`	string	Current trust tier: SELF_SIGNED, BASIC, VERIFIED, ENTERPRISE
`issuer_risk_rating`	string	Current risk assessment: LOW, MEDIUM, HIGH, CRITICAL
`issuer_jurisdiction`	string	Current registered jurisdiction (ISO 3166-1 alpha-2)
`issuer_display_name`	string	Human-readable issuer name for display in verification UIs
`primary_color`	string	Issuer brand primary color (hex)
`accent_color`	string	Issuer brand accent color (hex)
`logo_url`	string	URL to the issuer's logo image
`snapshot_status`	string	Issuer status at the time the attestation was minted
`snapshot_trust_tier`	string	Trust tier at the time of minting
`snapshot_risk_rating`	string	Risk rating at the time of minting
`snapshot_jurisdiction`	string	Jurisdiction at the time of minting

Trust Tiers

SELF_SIGNED

No external verification. The issuer self-attests their identity.

BASIC

Email and domain verified. Basic identity checks completed.

VERIFIED

Full KYC/KYB completed. Organization identity independently confirmed.

ENTERPRISE

Enterprise-grade verification with legal entity validation, compliance checks, and dedicated onboarding.

Risk Ratings

LOW

Minimal risk. Issuer has strong track record and compliance.

MEDIUM

Moderate risk. Some factors require monitoring.

HIGH

Elevated risk. Additional scrutiny recommended for verifications.

CRITICAL

Critical risk. Issuer may be suspended pending review.

Billing & 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.

Channel	Auth Required	Metered	Rate Limit
POST /v1/verify (API)	No	Yes — counted against issuer's plan quota	Plan-dependent (Starter: 1K/day, Growth: 10K/day, Enterprise: unlimited)
verify.truthlocks.com (Portal)	No	No — free and unlimited	Fair-use rate limiting only

HTTP 402 Payment Required: When the issuer's API verification quota is exhausted, the endpoint returns a 402 status with a BILLING_LIMIT error code. Upgrade the issuer's plan or wait for the quota to reset at the start of the next billing cycle.

Recommended: Share portal links

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}

POST/v1/verify

Language

cURL Request

Examples ▾

curl --request POST \
  --url https://sandbox-api.truthlocks.com/v1/verify \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --data '{
  "attestation_id": "660e8400-e29b-41d4-a716-446655440001"
}'

Response

Click Try It! to send a real request, or view sample responses: