> ## 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.
# Mint Attestation
> Legacy alias for `POST /v1/attestations`.
Kept for backward compatibility and rewritten by the gateway.
Creates a new cryptographically signed attestation. The attestation is signed using the specified issuer key and recorded in the transparency log with a unique log index for auditability.
### Supported Content Payloads
Attestations can be minted for any file type. Include the SHA-256 hash in the `document_hash` parameter to verify offline file integrity.
**Maximum Payload Size: 50 MB.** The base64url-encoded payload cannot exceed
50 MB after encoding.
| MIME Type | Extension | Category | Description |
| -------------------------- | ------------ | --------- | ------------------------------------------- |
| `application/pdf` | `.pdf` | Documents | PDF documents, contracts, reports, invoices |
| `application/json` | `.json` | Documents | Structured JSON claims (default) |
| `image/png` | `.png` | Images | PNG images, screenshots, scanned documents |
| `image/jpeg` | `.jpg/.jpeg` | Images | JPEG photos, ID scans, certificates |
| `image/webp` | `.webp` | Images | WebP images |
| `image/tiff` | `.tiff` | Images | TIFF images, high-resolution scans |
| `video/mp4` | `.mp4` | Video | MP4 video recordings, depositions, evidence |
| `video/webm` | `.webm` | Video | WebM video files |
| `audio/mpeg` | `.mp3` | Audio | MP3 audio recordings, voice attestations |
| `audio/wav` | `.wav` | Audio | WAV uncompressed audio |
| `application/octet-stream` | `any` | Other | Generic binary payload for any file type |
### Credential Schema Catalogue
The `schema` parameter determines the credential type and expected JSON claims structure.
| Schema ID | Name | Category | Claim Fields |
| ---------------------------- | -------------------------- | ----------------- | ------------------------------------------------------------------------------------------------------ |
| `verifiable-id` | Verifiable ID | Identity | `full_name, employee_id, department, title, start_date` |
| `passport` | Passport | Identity | `full_name, nationality, passport_number, date_of_birth, expiry_date, issuing_country` |
| `drivers-license` | Driver's License | Identity | `full_name, license_number, state, class, expiry_date, date_of_birth` |
| `government-id` | Government ID | Identity | `full_name, id_number, id_type, issuing_authority, country, expiry_date` |
| `self-sovereign-id` | Self-Sovereign ID | Identity | `did, display_name, created_at` |
| `employment-verification` | Employment Verification | Employment | `employee_name, employer, position, department, employment_type, start_date, end_date` |
| `professional-role` | Professional Role | Employment | `full_name, title, organization, department, effective_date` |
| `membership-card` | Membership Card | Employment | `member_name, organization, membership_id, tier, valid_from, valid_to` |
| `professional-certification` | Professional Certification | Employment | `holder_name, certification_name, issuing_body, certification_id, issued_date, expiry_date` |
| `license` | License | Employment | `holder_name, license_type, license_number, issuing_authority, jurisdiction, issued_date, expiry_date` |
| `accreditation` | Accreditation | Employment | `entity_name, accreditation_body, standard, scope, valid_from, valid_to` |
| `degree` | Degree | Education | `student_name, institution, degree_type, field_of_study, graduation_date, honors` |
| `completion-cert` | Completion Certificate | Education | `participant_name, program_name, institution, completion_date, hours` |
| `course-credit` | Course Credit | Education | `student_name, course_name, institution, credits, grade, semester` |
| `transcript` | Transcript | Education | `student_name, institution, program, gpa, total_credits, issue_date` |
| `micro-credential` | Micro-Credential | Education | `earner_name, credential_name, issuer, skills, earned_date` |
| `training-completion` | Training Completion | Education | `trainee_name, training_program, provider, completion_date, score, certificate_id` |
| `medical-license` | Medical License | Healthcare | `practitioner_name, license_number, specialty, state, issued_date, expiry_date` |
| `dea-registration` | DEA Registration | Healthcare | `registrant_name, dea_number, schedules, business_activity, expiry_date` |
| `board-certification` | Board Certification | Healthcare | `physician_name, board, specialty, certification_date, expiry_date` |
| `health-credential` | Health Credential | Healthcare | `patient_name, credential_type, provider, date, details` |
| `vaccination-record` | Vaccination Record | Healthcare | `patient_name, vaccine_name, manufacturer, lot_number, date_administered, dose_number, site` |
| `aml-kyc` | AML/KYC Check | Compliance | `entity_name, check_type, result, risk_level, verified_by, verified_at` |
| `security-clearance` | Security Clearance | Compliance | `holder_name, clearance_level, granting_agency, granted_date, expiry_date` |
| `sam-gov` | SAM.gov Registration | Compliance | `entity_name, cage_code, uei, registration_status, expiry_date` |
| `jurisdiction-approval` | Jurisdiction Approval | Compliance | `entity_name, jurisdiction, approval_type, approved_date, conditions` |
| `attestation-of-will` | Attestation of Will | Compliance | `declarant_name, declaration, witness, date` |
| `bank-verification` | Bank Verification | Financial | `account_holder, bank_name, account_type, routing_number_last4, verified_date` |
| `credit-attestation` | Credit Attestation | Financial | `entity_name, credit_score_range, reporting_agency, assessment_date` |
| `income-verification` | Income Verification | Financial | `individual_name, employer, annual_income_range, verification_date, tax_year` |
| `skill-badge` | Skill Badge | Skills & Training | `earner_name, skill_name, proficiency_level, assessed_by, earned_date` |
| `competency` | Competency Attestation | Skills & Training | `individual_name, competency, level, assessor, assessment_date` |
| `industry-cert` | Industry Certification | Skills & Training | `holder_name, certification, issuing_body, cert_id, issued_date, expiry_date` |
| `product-authenticity` | Product Authenticity | Supply Chain | `product_name, sku, serial_number, manufacturer, manufactured_date, origin_country` |
| `chain-of-custody` | Chain of Custody | Supply Chain | `item_description, from_entity, to_entity, transfer_date, location, condition` |
| `origin-verification` | Origin Verification | Supply Chain | `product_name, origin_country, origin_region, certifying_body, verified_date` |
| `custom` | Custom | Other | `subject, type, details` |
| `attestation` | Generic Attestation | Other | `subject, claim, evidence` |
***
### Document hash for file integrity
When attesting a document or file, include the `document_hash` parameter with the hex-encoded SHA-256 hash of the original file. Verifiers can then confirm the file has not been altered by comparing their computed hash against the stored value — without needing the full payload.
The platform resolves the document hash using the following priority:
1. `claims.document.sha256` inside the JSON payload
2. The explicit `document_hash` field on the request body
3. Auto-computed SHA-256 of the raw payload bytes (fallback)
For best results, always compute the hash client-side and pass it explicitly:
```bash theme={null}
# Compute the SHA-256 hash of a file
HASH=$(shasum -a 256 contract.pdf | awk '{print $1}')
curl -X POST https://api.truthlocks.com/v1/attestations/mint \
-H "X-API-Key: tl_live_..." \
-H "Idempotency-Key: unique-request-id" \
-H "Content-Type: application/json" \
-d '{
"issuer_id": "550e8400-e29b-41d4-a716-446655440000",
"kid": "ed-key-2026",
"alg": "Ed25519",
"document_hash": "'"$HASH"'",
"payload_b64url": "",
"content_type": "application/pdf"
}'
```
At verification time, pass the same hash as `document_hash_hex` to the [Verify endpoint](/api-reference/verify) to confirm file integrity without re-uploading the file.
If you omit `document_hash` and don't include `claims.document.sha256` in your payload, the platform computes the hash automatically from the raw payload bytes. Passing it explicitly is recommended because it ensures the hash matches the original file before any base64url encoding.
***
### Example: Email Credential Delivery (B2C)
Include `recipient_email` in the request body
System checks if email exists in consumer portal
Existing users receive inbox notifications. New users receive a signup
invite holding their pending attestations.
The `recipient_email` is entirely optional. If omitted, you must deliver the
attestation URLs to your users manually.
## OpenAPI
````yaml mint-openapi.yaml POST /v1/attestations/mint
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/attestations/mint:
post:
tags:
- Attestations
summary: Mint Attestation
description: |
Legacy alias for `POST /v1/attestations`.
Kept for backward compatibility and rewritten by the gateway.
parameters:
- name: Idempotency-Key
in: header
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- issuer_id
- kid
- alg
- schema
- claims
properties:
issuer_id:
type: string
format: uuid
description: The UUID of the issuer creating the attestation
example: 550e8400-e29b-41d4-a716-446655440000
kid:
type: string
description: Key identifier for the signing key
example: es256-key-1
alg:
$ref: '#/components/schemas/SigningAlgorithm'
description: Cryptographic algorithm used for signing
example: ES256
schema:
type: string
description: >
Credential schema type (e.g. verifiable-id, passport,
degree, aml-kyc). See full list below.
enum:
- verifiable-id
- passport
- drivers-license
- government-id
- self-sovereign-id
- employment-verification
- professional-role
- membership-card
- professional-certification
- license
- accreditation
- degree
- completion-cert
- course-credit
- transcript
- micro-credential
- training-completion
- medical-license
- dea-registration
- board-certification
- health-credential
- vaccination-record
- aml-kyc
- security-clearance
- sam-gov
- jurisdiction-approval
- attestation-of-will
- bank-verification
- credit-attestation
- income-verification
- skill-badge
- competency
- industry-cert
- product-authenticity
- chain-of-custody
- origin-verification
- custom
- attestation
example: verifiable-id
claims:
type: object
additionalProperties:
type: string
description: >
The structured claims for this credential. Fields depend on
the selected schema. See schema catalogue below.
example:
full_name: ''
employee_id: ''
department: ''
title: ''
start_date: ''
recipient_email:
type: string
format: email
description: >
Email address of the credential recipient. When provided,
the platform sends a notification email with a link to view
the attestation on the consumer portal
(verify.truthlocks.com). If the recipient does not have a
consumer portal account, they receive an invitation to sign
up. This enables B2C credential delivery workflows.
document_hash:
type: string
description: >
Hex-encoded SHA-256 hash of the document or file being
attested. Used for document integrity verification —
verifiers can recompute the hash of the original file and
compare it against this stored value. If omitted, the system
checks for claims.document.sha256 in the payload, and if
that is also absent, auto-computes the SHA-256 of the raw
payload bytes. For best results, compute the hash
client-side before base64url-encoding the payload.
pack_id:
type: string
format: uuid
description: >
UUID of the verification pack to link this attestation to.
The pack must be in 'active' status. When provided, the
pack's verifications_count is automatically incremented. Use
this to organize attestations by verification program and
track analytics per pack.
content_type:
type: string
description: >
MIME type of the payload. Supported: application/json
(default), application/pdf, image/png, image/jpeg,
image/webp, image/tiff, video/mp4, video/webm, audio/mpeg,
audio/wav, application/octet-stream. Max payload size: 50
MB.
example: application/json
responses:
'201':
description: Attestation minted
content:
application/json:
schema:
$ref: '#/components/schemas/Attestation'
example:
id: 660e8400-e29b-41d4-a716-446655440001
issuer_id: 550e8400-e29b-41d4-a716-446655440000
kid: ed-key-1
status: VALID
log_index: 42
created_at: '2026-01-13T12:00:00Z'
'400':
description: Invalid request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'413':
description: Payload too large
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
example:
code: PAYLOAD_TOO_LARGE
message: Request body exceeds maximum size of 1MB
http_status: 413
'429':
description: Rate limit or quota exceeded
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
example:
code: RATE_LIMIT_EXCEEDED
message: Rate limit exceeded
http_status: 429
retry_after_ms: 60000
security:
- APIKey: []
components:
schemas:
SigningAlgorithm:
type: string
enum:
- Ed25519
- ES256
- ES384
- ES512
- RS256
- RS384
- RS512
- PS256
- PS384
- PS512
description: Signing algorithm for key generation
Attestation:
type: object
properties:
id:
type: string
format: uuid
issuer_id:
type: string
format: uuid
kid:
type: string
status:
type: string
enum:
- VALID
- REVOKED
- SUPERSEDED
payload:
type: object
signature:
type: string
log_index:
type: integer
created_at:
type: string
format: date-time
ErrorEnvelope:
type: object
required:
- code
- message
- http_status
properties:
code:
type: string
description: Machine-readable error code
enum:
- AUTH_REQUIRED
- AUTH_INVALID
- PERMISSION_DENIED
- TENANT_IDENTITY_UNVERIFIED
- NOT_FOUND
- VALIDATION_ERROR
- CONFLICT
- PAYLOAD_TOO_LARGE
- RATE_LIMIT_EXCEEDED
- QUOTA_EXCEEDED
- SERVICE_UNAVAILABLE
- INTERNAL_ERROR
message:
type: string
description: Human-readable error message
http_status:
type: integer
description: HTTP status code
retry_after_ms:
type: integer
description: Milliseconds to wait before retrying (for rate limits)
details:
type: object
description: Additional error context
example:
code: AUTH_REQUIRED
message: Authentication required
http_status: 401
securitySchemes:
APIKey:
type: apiKey
in: header
name: X-API-Key
description: API key for machine-to-machine authentication
````