Skip to main content
POST
Mint Attestation
Signs a payload using an issuer’s available signing key and records the resulting attestation. Issuer policy, key status, environment, and usage limits can prevent minting.

Choose a record type

For a structured record, choose schema from the record-type dropdown and enter a JSON object in claims. Leave payload_b64url empty. The server serializes these fields into the signed JSON payload. This identifies the record type; it does not independently establish that the claims are true.

Choose a verification pack

Verification packs belong to your workspace. Use the selector below with the same environment and API key as Try it, then copy the selected ID into pack_id. Omit that field for a standalone record. You can also use List verification packs or Mint in Console.

Use an existing payload

If you already have the exact bytes to sign, omit schema and claims. Encode the original bytes as unpadded base64url in payload_b64url. For JSON, serialize the object first. Application fields such as subject, claims, and schema belong inside those encoded bytes; use them either through the structured input above or inside the encoded bytes, never both. This endpoint does not independently verify the truth of submitted claims or validate arbitrary credential schemas. Use the key’s kid and matching alg. Public-key registration alone does not make a private signing key available. See issuer keys.

Optional expiry

For structured schema and claims, set expires_at_unix to a future Unix timestamp in seconds. Truthlocks includes it at the root of the signed JSON payload. With payload_b64url, put this field inside the exact JSON payload before encoding it and omit the separate request field. After that instant, verification returns EXPIRED. Expiry cannot be extended or removed from an existing signed record; mint a replacement. Omit it when you do not want an attestation expiry. Dates inside individual claims, such as a passport’s expiry_date, are separate claims and do not automatically set the attestation expiry. Existing records are not assigned a date retrospectively. Retain the exact payload and expiry when retrying. An idempotent retry returns the original record even after its expiry.

Retry safely

Idempotency-Key is required. Generate one value per intended mint and retain it with the original request for retries. Do not reuse it for different content.

Document integrity

The stored document hash is selected in this order:
  1. claims.document.sha256 inside a JSON payload.
  2. The request’s document_hash.
  3. SHA-256 of the decoded payload bytes.
An embedded hash takes precedence over the separate field. Include the hash in the signed payload when you need to bind that claim to the signature. A submitted hash is a claim about a file; the server cannot establish the file’s contents from the hash alone. Pass document_hash_hex to verification to compare a file hash. Keep the original payload for payload-integrity verification.

Response and delivery

HTTP 201 returns attestation_id, issued_at_unix, signature, and log. The log position is log.leaf_index, not a top-level log_index. recipient_email requests asynchronous notification. HTTP 201 confirms minting, not email delivery. Omit it when distributing the record yourself. See the quickstart for a request using the actual input and response fields.

Record-type field guide

These fields are suggested claim structures, not a claim-validation or identity-check guarantee.

Authorizations

X-API-Key
string
header
required

API key for machine-to-machine authentication

Headers

Idempotency-Key
string
required

Retain the same value and request body when retrying one mint.

Body

application/json

Choose Structured record to select a record type and enter claims, or Encoded payload to sign existing bytes. Never combine both input formats.

alg
enum<string>
required

Must match the selected issuer signing key.

Available options:
Ed25519,
ES256,
ES384,
ES512,
RS256,
RS384,
RS512,
PS256,
PS384,
PS512
issuer_id
string<uuid>
required

The UUID of the issuer creating the attestation

Example:

"550e8400-e29b-41d4-a716-446655440000"

kid
string
required

Key identifier for the signing key

Example:

"es256-key-1"

schema
enum<string>
required

Record type for structured input. Provide claims and omit payload_b64url. This label does not independently validate the truth of claims.

Available options:
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
object
required

Structured record fields. Required with schema; cannot be combined with payload_b64url.

Example:
attestation_id
string
content_type
string

MIME type of the original bytes, such as application/json, application/pdf or image/png. Structured schema/claims input requires application/json.

Example:

"application/json"

document_hash
string

Optional hexadecimal SHA-256 document hash. An embedded claims.document.sha256 takes precedence; otherwise this field is used, then the decoded payload hash.

pack_id
string<uuid>

Optional workspace verification-pack UUID. Use List verification packs with the same API key to select an existing active pack; omit for a standalone record.

expires_at_unix
integer<int64>

Optional future Unix timestamp in seconds for structured schema/claims input. It is included in the signed JSON payload. For payload_b64url input, omit this request field and embed expires_at_unix at the root of the exact JSON payload instead. Expiry cannot be changed in place.

Required range: 1 <= x <= 253402300799
recipient_email
string<email>

Optional recipient for asynchronous notification after minting. A successful mint response does not confirm delivery.

Response

Attestation minted

attestation_id
string<uuid>
issuer_id
string<uuid>
version
string
status
string
expires_at_unix
integer<int64> | null

Recorded signed expiry in Unix seconds; null means no expiry is recorded. Legacy records are not assigned a new expiry.

issued_at_unix
integer<int64>
payload_hash
string
signature
object
log
object
governance
object | null