# Approve agent approval Source: https://docs.truthlocks.com/api-reference/agent-approvals/approve maip-openapi.yaml POST /v1/approvals/{approvalID}/approve Records one approval from an active human with tenant:governance:approve in this workspace. Requesters and previous reviewers cannot vote. Status remains pending until the distinct-reviewer quorum is met. API keys cannot review. Records one approval from an active human with tenant:governance:approve in this workspace. Requesters and previous reviewers cannot vote. Status remains pending until the distinct-reviewer quorum is met. API keys cannot review. See [independent agent reviews](/guides/agent-approvals) for the authorization and execution boundaries. # Cancel agent approval Source: https://docs.truthlocks.com/api-reference/agent-approvals/cancel maip-openapi.yaml POST /v1/approvals/{approvalID}/cancel Only the authenticated original requester may cancel a pending, unexpired request. Human users and the same original API key can cancel their own requests. Cancellation preserves the record and earlier reviews. Only the authenticated original requester may cancel a pending, unexpired request. Human users and the same original API key can cancel their own requests. Cancellation preserves the record and earlier reviews. See [independent agent reviews](/guides/agent-approvals) for the authorization and execution boundaries. # Request agent approval Source: https://docs.truthlocks.com/api-reference/agent-approvals/create maip-openapi.yaml POST /v1/approvals Records a request for independent human review. Does not execute an agent action, grant permissions, or automatically pause or resume a Temporal workflow. Records a request for independent human review. Does not execute an agent action, grant permissions, or automatically pause or resume a Temporal workflow. See [independent agent reviews](/guides/agent-approvals) for the authorization and execution boundaries. # Get agent approval Source: https://docs.truthlocks.com/api-reference/agent-approvals/get maip-openapi.yaml GET /v1/approvals/{approvalID} Returns the request and immutable reviewer history. Expired pending requests are reported as expired even before any decision attempt. Returns the request and immutable reviewer history. Expired pending requests are reported as expired even before any decision attempt. See [independent agent reviews](/guides/agent-approvals) for the authorization and execution boundaries. # List pending agent approvals Source: https://docs.truthlocks.com/api-reference/agent-approvals/list maip-openapi.yaml GET /v1/approvals Returns at most 100 oldest pending, unexpired requests in the authenticated environment. No pagination or status filter is supported. Save request IDs to retrieve completed records. Individual review history is returned by the get endpoint. Returns at most 100 oldest pending, unexpired requests in the authenticated environment. No pagination or status filter is supported. Save request IDs to retrieve completed records. Individual review history is returned by the get endpoint. See [independent agent reviews](/guides/agent-approvals) for the authorization and execution boundaries. # Reject agent approval Source: https://docs.truthlocks.com/api-reference/agent-approvals/reject maip-openapi.yaml POST /v1/approvals/{approvalID}/reject An independent authorized human reviewer may reject once. One rejection immediately closes the request. Requesters, previous reviewers, API keys, and expired requests cannot be reviewed. An independent authorized human reviewer may reject once. One rejection immediately closes the request. Requesters, previous reviewers, API keys, and expired requests cannot be reviewed. See [independent agent reviews](/guides/agent-approvals) for the authorization and execution boundaries. # Create agent receipt Source: https://docs.truthlocks.com/api-reference/agent-receipts/create maip-openapi.yaml POST /v1/agent-receipts Stores a signed version 2 MAIP action receipt for an active agent. This is separate from the general receipts API. Integration metadata is signed; transparency inclusion is not established. Stores a signed version 2 MAIP action receipt for an active agent. This is separate from the general receipts API. Integration metadata is signed; transparency inclusion is not established. Use a workspace API key or bearer token. Encode the complete `maip-receipt:` identifier as one URL path segment. # Get agent receipt Source: https://docs.truthlocks.com/api-reference/agent-receipts/get maip-openapi.yaml GET /v1/agent-receipts/{receiptID} Retrieve a receipt in the authenticated workspace. Retrieve a receipt in the authenticated workspace. Use a workspace API key or bearer token. Encode the complete `maip-receipt:` identifier as one URL path segment. # List agent receipts Source: https://docs.truthlocks.com/api-reference/agent-receipts/list maip-openapi.yaml GET /v1/agent-receipts/agent/{agentID} List receipts for one workspace agent. List receipts for one workspace agent. Use a workspace API key or bearer token. Use the agent identifier from your workspace as `agentID`; this endpoint lists that agent's receipts. # Verify agent receipt Source: https://docs.truthlocks.com/api-reference/agent-receipts/verify maip-openapi.yaml GET /v1/agent-receipts/verify/{receiptID} Verify signed fields against the retained public key and check lifecycle state. Old receipts with lost keys are UNVERIFIABLE. Rotation retains historical verification. This endpoint does not verify transparency-log inclusion. Verify signed fields against the retained public key and check lifecycle state. Old receipts with lost keys are UNVERIFIABLE. Rotation retains historical verification. This endpoint does not verify transparency-log inclusion. Use a workspace API key or bearer token. Encode the complete `maip-receipt:` identifier as one URL path segment. # List announcements Source: https://docs.truthlocks.com/api-reference/announcements/list mint-openapi.yaml GET /v1/messages Retrieve platform announcements for your tenant. Returns all announcements sent to your tenant by the Truthlocks platform. Announcements include system updates, security alerts, and operational notifications. You can also view announcements in the console. See the [console onboarding guide](/guides/console-onboarding#announcements) for details on the announcements inbox. ### Responses ### Announcement priority levels | Priority | Description | | :- | :- | | `NORMAL` | General platform updates and informational messages. | | `URGENT` | Time-sensitive changes that may affect your workflows. | | `CRITICAL` | Security alerts or service disruptions requiring immediate attention. | # Mark announcement as read Source: https://docs.truthlocks.com/api-reference/announcements/mark-read mint-openapi.yaml POST /v1/messages/{id}/read Mark a single announcement as read for your tenant. Marks the specified announcement as read. This updates the `is_read` field to `true` and removes the unread indicator in the console. ### Responses # Create API Key Source: https://docs.truthlocks.com/api-reference/api-keys/create mint-openapi.yaml POST /v1/api-keys Creates a new API key. The secret is returned once and cannot be retrieved again. Creates a new API key for the authenticated organization. The secret is returned ONCE and cannot be retrieved again. Store it securely. ### Responses # Revoke an API key Source: https://docs.truthlocks.com/api-reference/api-keys/delete mint-openapi.yaml DELETE /v1/api-keys/{id} Revoke API Key Use the key record ID, not the secret token. Revocation disables future authentication with that credential. Update integrations to another authorized key before revoking a key they still use. # List API Keys Source: https://docs.truthlocks.com/api-reference/api-keys/list mint-openapi.yaml GET /v1/api-keys Returns all API keys for the authenticated organization. Secrets are masked. Returns all API keys for the authenticated organization. Secrets are masked and not returned in this endpoint. ### Responses # Revoke API Key Source: https://docs.truthlocks.com/api-reference/api-keys/revoke mint-openapi.yaml POST /v1/api-keys/{id}/revoke Permanently revokes an API key. This action cannot be undone. Permanently revokes an API key. This action cannot be undone. All requests using this key will immediately return 401 Unauthorized. ### Responses # Retrieve an asset Source: https://docs.truthlocks.com/api-reference/assets/get mint-openapi.yaml GET /v1/assets/{id} Retrieve a stored asset by its returned ID. The response streams bytes with the stored content type. Handle HTTP errors before treating the body as a file. Retrieval is distinct from document or identity verification. # Upload an asset Source: https://docs.truthlocks.com/api-reference/assets/upload mint-openapi.yaml POST /v1/assets/upload Uploads a file to the asset store for use with issuers, evidence, and branding. Send a file as multipart field `file`, within the 5 MB request limit. The multipart envelope also uses request space, so keep the file below the limit. Save the returned asset identifier for later retrieval. The endpoint stores the submitted bytes; it does not independently establish that uploaded evidence is authentic. See [Retrieve asset](/api-reference/assets/get) for access to a stored file. # Get Barcode Source: https://docs.truthlocks.com/api-reference/attestations/barcode mint-openapi.yaml GET /v1/attestations/{id}/barcode Generate a Code 128 barcode image for an attestation. The barcode encodes only the attestation ID, making it compact enough for physical labels, receipts, and packaging. ### Use cases * Supply chain labels and inventory tags * Physical receipts and access cards * Printed documents where space is limited * Barcode scanner-friendly environments (warehouses, retail) ### Response Returns a PNG image with `Content-Type: image/png`. The response includes aggressive cache headers (`Cache-Control: public, max-age=31536000, immutable`) since barcodes for a given attestation never change. ### Encoded data The barcode contains the raw attestation UUID string. To verify, scan the barcode with any Code 128 reader, then look up the attestation using the ID. ### QR code vs barcode: when to use which | Scenario | Use QR | Use Barcode | | - | - | - | | Digital certificates | Yes | No | | Physical labels | Maybe | Yes | | Supply chain | No | Yes | | Email badges | Yes | No | | Access cards | Either | Either | | Mobile sharing | Yes | No | ```bash cURL theme={null} curl -H "Authorization: Bearer $API_KEY" \ "https://api.truthlocks.com/v1/attestations/550e8400-e29b-41d4-a716-446655440000/barcode?width=400&height=100" \ --output attestation-barcode.png ``` ```typescript SDK theme={null} const barcodeImage = await client.attestations.getBarcode(attestationId, { width: 400, height: 100 }); fs.writeFileSync('attestation-barcode.png', Buffer.from(barcodeImage)); ``` # Batch Generate Codes Source: https://docs.truthlocks.com/api-reference/attestations/batch-codes mint-openapi.yaml POST /v1/attestations/codes/batch Generate QR codes and/or barcodes for multiple attestations at once. Returns a ZIP file containing all requested code images. ### Use cases * Bulk certificate printing with QR codes * Generating labels for an entire product batch * Exporting verification codes for offline distribution ### Response Returns a ZIP file (`Content-Type: application/zip`) containing PNG images named: * `{attestation_id}-qr.png` for QR codes * `{attestation_id}-barcode.png` for barcodes ### Rate limits Batch requests are rate-limited to 10 requests per minute. Each request can contain up to 100 attestation IDs. ```bash cURL theme={null} curl -X POST \ -H "Authorization: Bearer $API_KEY" \ -H "Content-Type: application/json" \ -d '{ "ids": [ "550e8400-e29b-41d4-a716-446655440000", "6ba7b810-9dad-11d1-80b4-00c04fd430c8" ], "type": "both", "size": 512 }' \ "https://api.truthlocks.com/v1/attestations/codes/batch" \ --output verification-codes.zip ``` ```typescript SDK theme={null} const zipBuffer = await client.attestations.getBatchCodes( ['550e8400-e29b-41d4-a716-446655440000', '6ba7b810-9dad-11d1-80b4-00c04fd430c8'], { type: 'both', size: 512 } ); fs.writeFileSync('verification-codes.zip', Buffer.from(zipBuffer)); ``` # Get Attestation Source: https://docs.truthlocks.com/api-reference/attestations/get mint-openapi.yaml GET /v1/attestations/{id} Returns details for a specific attestation. Retrieves a specific attestation by its unique ID. Returns the full attestation payload, signature, and status information. ### Responses # List Attestations Source: https://docs.truthlocks.com/api-reference/attestations/list mint-openapi.yaml GET /v1/attestations Returns attestations for the authenticated tenant with pagination. Returns attestations for the authenticated tenant with pagination. Filter by issuer\_id or use cursor-based pagination for large result sets. ### Responses # Mint Attestation Source: https://docs.truthlocks.com/api-reference/attestations/mint mint-openapi.yaml POST /v1/attestations/mint Mint a signed attestation using structured schema and claims, or an encoded payload. Retain the same Idempotency-Key and body when retrying this request. 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](/api-reference/verification-packs/list) or [Mint in Console](https://console.truthlocks.com/attestations/mint). **Select a workspace verification pack** This read-only lookup sends your key directly to the selected Truthlocks API. It keeps the key only in this component’s memory and does not mint a record. API environment Workspace API key Clear key and results Verification pack ## 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](/api-reference/issuers/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](/api-reference/verify) 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](/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. | 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` | # Mint through the collection route Source: https://docs.truthlocks.com/api-reference/attestations/mint-alias mint-openapi.yaml POST /v1/attestations Mint Attestation This is the collection-route variant of attestation minting. Use the structured-record or encoded-payload option shown in Try It and retain the same Idempotency-Key when retrying the same request. Verification packs and record types remain selectable in the request schema. # Get Proof Bundle Source: https://docs.truthlocks.com/api-reference/attestations/proof-bundle mint-openapi.yaml GET /v1/attestations/{id}/proof-bundle Returns a complete proof bundle for offline verification. Includes: - The attestation itself - Issuer information - Public key used for signing - Transparency log inclusion proof - Signed tree head Returns a complete proof bundle for offline verification. Includes the attestation, issuer information, public key, transparency log inclusion proof, and signed tree head. ### Responses # Get QR Code Source: https://docs.truthlocks.com/api-reference/attestations/qr-code mint-openapi.yaml GET /v1/attestations/{id}/qr Generate a QR code image for an attestation. The QR code encodes the full verification URL that anyone can scan to verify the attestation independently. ### Use cases * Print on certificates, badges, and documents * Embed in emails or digital proof pages * Display on screens for instant mobile verification ### Response Returns a PNG image with `Content-Type: image/png`. The response includes aggressive cache headers (`Cache-Control: public, max-age=31536000, immutable`) since QR codes for a given attestation never change. ### Encoded URL format The QR code encodes: ``` https://verify.truthlocks.com/proof/{attestation_id} ``` Anyone who scans this QR code will be taken directly to the verification page for this attestation. ```bash cURL theme={null} curl -H "Authorization: Bearer $API_KEY" \ "https://api.truthlocks.com/v1/attestations/550e8400-e29b-41d4-a716-446655440000/qr?size=512" \ --output attestation-qr.png ``` ```typescript SDK theme={null} const qrImage = await client.attestations.getQRCode(attestationId, { size: 512 }); fs.writeFileSync('attestation-qr.png', Buffer.from(qrImage)); ``` # Revoke Attestation Source: https://docs.truthlocks.com/api-reference/attestations/revoke mint-openapi.yaml POST /v1/attestations/{id}/revoke Revokes an attestation, marking it as invalid for future verification. This action is recorded in the transparency log and cannot be undone. Revokes an attestation, marking it as invalid for future verification. This action is recorded in the transparency log and cannot be undone. Existing proof bundles will show REVOKED status. ### Responses # Supersede Attestation Source: https://docs.truthlocks.com/api-reference/attestations/supersede mint-openapi.yaml POST /v1/attestations/{id}/supersede Creates a new attestation that supersedes an existing one. The original attestation is marked as SUPERSEDED. Creates a new attestation that supersedes an existing one. The original attestation is marked as `SUPERSEDED` with a reference to the new version. The new attestation is signed with the specified key, recorded in the transparency log, and returned alongside the updated original. Both attestations remain verifiable, creating an auditable chain of credential versions. Only `VALID` attestations can be superseded — `REVOKED` or already `SUPERSEDED` attestations return a `409 Conflict`. ### How it works **1. Call supersede with original attestation ID** Provide the UUID of the attestation to supersede as a path parameter, along with the new payload and signing key. **2. Original attestation marked SUPERSEDED** The original attestation's status changes to `SUPERSEDED` with a timestamp and a reference to the new attestation ID. **3. New attestation created with VALID status** A new attestation is minted with the updated payload, signed with the specified key, and recorded in the transparency log. **4. Both returned in response** The response includes both the old (superseded) and new (valid) attestation objects under `old` and `new` keys. ### Common use cases | Use case | Scenario | Example | | - | - | - | | Credential update | Employee changes role or department | Supersede old employment verification with updated title | | Renewal | Certificate or license expires and is renewed | Supersede expired medical license with new expiry date | | Error correction | Typo or incorrect data in original credential | Supersede passport attestation with corrected name | | Version upgrade | Schema or claims format changes | Supersede v1 credential with v2 format | | Key rotation | Signing key compromised or rotated | Supersede attestation signed with old key using new key | ### Responses > [!NOTE] > > Supersede operations are idempotent when using the same `Idempotency-Key`. Retrying a failed request with the same key is safe and will not create duplicate attestations. > [!WARNING] > > The original attestation remains in the transparency log and can still be verified. Its status changes to `SUPERSEDED` but the cryptographic proof is preserved. Verifiers can trace the full supersession chain by following the `superseded_by_attestation_id` field. # Request audit export Source: https://docs.truthlocks.com/api-reference/audit/export mint-openapi.yaml POST /v1/audit/exports Creates an asynchronous audit event export job. Requests an export using `format`, `from_ts`, `to_ts`, and optional `filter`. The date fields are timestamps; `start_date`, `end_date`, and `report_type` are not supported fields. Export storage must be configured and workspace retention policy must permit exports. Poll the export record and download only after completion; request acceptance is not proof that a file exists. This operation exports audit events, not an independent SOC 2, GDPR, or HIPAA certification. # Query Audit Events Source: https://docs.truthlocks.com/api-reference/audit/query mint-openapi.yaml GET /v1/audit Returns audit events for the authenticated tenant. Returns audit events for the authenticated tenant. Filter by actor, action, resource type, or time range. ### Responses # Get retention policy Source: https://docs.truthlocks.com/api-reference/audit/retention-get mint-openapi.yaml GET /v1/audit/retention Retrieve the current audit log retention policy for the authenticated tenant. Returns the active retention policy for the authenticated tenant. If an environment-specific policy exists, it takes precedence over the global policy. Requires the `tenant.audit.retention.read` permission. ### Responses # Update retention policy Source: https://docs.truthlocks.com/api-reference/audit/retention-update mint-openapi.yaml PUT /v1/audit/retention Update the audit log retention policy for the authenticated tenant. Updates the retention policy that controls how long audit logs are kept and what happens when they expire. Requires the `tenant.audit.retention.manage` permission. ### Responses # Create SIEM destination Source: https://docs.truthlocks.com/api-reference/audit/siem/create mint-openapi.yaml POST /v1/audit/siem Manage protected, environment-scoped audit delivery destinations. > [!NOTE] > > Check `delivery_available` in the list response before enabling a destination. Delivery covers new audit events with verified environment attribution. Historical and unattributed events are not streamed. An `enabled` destination is not evidence of successful ingestion; inspect `delivery_counts` and your receiver. Use the API key for the intended sandbox or production environment. Listing requires `audit:read`; changes require `audit:write`. A browser session must belong to a workspace administrator. A destination from another tenant or environment cannot be updated or deleted. Credentials are encrypted at rest and never appear in responses. For webhooks supply `secret`; for Splunk, Datadog or Elastic supply `token`. Changing an endpoint requires supplying its credential again. CloudWatch configuration is not supported. An environment can hold up to 20 destinations. Deleting a destination removes its saved credential and queued delivery records. Disabling or changing a destination cancels its pending deliveries; save any delivery evidence you need first. See the [SIEM delivery guide](/guides/siem-integration) for retries, provider settings and webhook verification. For snapshot ingestion, use [audit exports](/api-reference/audit/export) or [risk-event exports](/api-reference/risk/exports/create). These exports do not enable continuous streaming. # Delete SIEM destination Source: https://docs.truthlocks.com/api-reference/audit/siem/delete mint-openapi.yaml DELETE /v1/audit/siem/{id} Manage protected, environment-scoped audit delivery destinations. > [!NOTE] > > Check `delivery_available` in the list response before enabling a destination. Delivery covers new audit events with verified environment attribution. Historical and unattributed events are not streamed. An `enabled` destination is not evidence of successful ingestion; inspect `delivery_counts` and your receiver. Use the API key for the intended sandbox or production environment. Listing requires `audit:read`; changes require `audit:write`. A browser session must belong to a workspace administrator. A destination from another tenant or environment cannot be updated or deleted. Credentials are encrypted at rest and never appear in responses. For webhooks supply `secret`; for Splunk, Datadog or Elastic supply `token`. Changing an endpoint requires supplying its credential again. CloudWatch configuration is not supported. An environment can hold up to 20 destinations. Deleting a destination removes its saved credential and queued delivery records. Disabling or changing a destination cancels its pending deliveries; save any delivery evidence you need first. See the [SIEM delivery guide](/guides/siem-integration) for retries, provider settings and webhook verification. For snapshot ingestion, use [audit exports](/api-reference/audit/export) or [risk-event exports](/api-reference/risk/exports/create). These exports do not enable continuous streaming. # List SIEM destination Source: https://docs.truthlocks.com/api-reference/audit/siem/list mint-openapi.yaml GET /v1/audit/siem Manage protected, environment-scoped audit delivery destinations. > [!NOTE] > > Check `delivery_available` in the list response before enabling a destination. Delivery covers new audit events with verified environment attribution. Historical and unattributed events are not streamed. An `enabled` destination is not evidence of successful ingestion; inspect `delivery_counts` and your receiver. Use the API key for the intended sandbox or production environment. Listing requires `audit:read`; changes require `audit:write`. A browser session must belong to a workspace administrator. A destination from another tenant or environment cannot be updated or deleted. Credentials are encrypted at rest and never appear in responses. For webhooks supply `secret`; for Splunk, Datadog or Elastic supply `token`. Changing an endpoint requires supplying its credential again. CloudWatch configuration is not supported. An environment can hold up to 20 destinations. Deleting a destination removes its saved credential and queued delivery records. Disabling or changing a destination cancels its pending deliveries; save any delivery evidence you need first. See the [SIEM delivery guide](/guides/siem-integration) for retries, provider settings and webhook verification. For snapshot ingestion, use [audit exports](/api-reference/audit/export) or [risk-event exports](/api-reference/risk/exports/create). These exports do not enable continuous streaming. # Update SIEM destination Source: https://docs.truthlocks.com/api-reference/audit/siem/update mint-openapi.yaml PUT /v1/audit/siem/{id} Manage protected, environment-scoped audit delivery destinations. > [!NOTE] > > Check `delivery_available` in the list response before enabling a destination. Delivery covers new audit events with verified environment attribution. Historical and unattributed events are not streamed. An `enabled` destination is not evidence of successful ingestion; inspect `delivery_counts` and your receiver. Use the API key for the intended sandbox or production environment. Listing requires `audit:read`; changes require `audit:write`. A browser session must belong to a workspace administrator. A destination from another tenant or environment cannot be updated or deleted. Credentials are encrypted at rest and never appear in responses. For webhooks supply `secret`; for Splunk, Datadog or Elastic supply `token`. Changing an endpoint requires supplying its credential again. CloudWatch configuration is not supported. An environment can hold up to 20 destinations. Deleting a destination removes its saved credential and queued delivery records. Disabling or changing a destination cancels its pending deliveries; save any delivery evidence you need first. See the [SIEM delivery guide](/guides/siem-integration) for retries, provider settings and webhook verification. For snapshot ingestion, use [audit exports](/api-reference/audit/export) or [risk-event exports](/api-reference/risk/exports/create). These exports do not enable continuous streaming. # Export accounting records Source: https://docs.truthlocks.com/api-reference/billing/accounting-export mint-openapi.yaml GET /v1/billing/exports/accounting Download accounting records for `from` and `to` dates in `YYYY-MM-DD` format. The default range is the last 30 days. The default format is `csv`; use `json` for a JSON export. Treat the response as a file and inspect its content type. The current handler falls back to defaults for unparseable dates; validate dates in your client. # Attach an add-on Source: https://docs.truthlocks.com/api-reference/billing/addons mint-openapi.yaml POST /v1/billing/addons/attach Attaches a billing addon to the tenant's subscription. Supply `addon_key` and an explicit `quantity` between 1 and 10000. The handler does not default an omitted quantity to one. For a priced add-on, the response includes `checkout_url` and `status: pending_payment`. A checkout URL is not evidence that payment completed. Free add-ons return HTTP 200 with no JSON body. Use current workspace entitlements to confirm activation. [Detach an add-on](/api-reference/billing/addons-detach) is a separate request. Catalog availability, pricing, and support commitments depend on your agreement and configured billing provider. # Detach an add-on Source: https://docs.truthlocks.com/api-reference/billing/addons-detach mint-openapi.yaml POST /v1/billing/addons/detach Detaches a billing addon from the tenant's subscription. Submit the add-on key to remove its workspace association. Success returns HTTP 200 with no JSON body. Check the resulting subscription and entitlements; this operation does not itself promise a refund or an end-of-period cancellation. # Cancel subscription Source: https://docs.truthlocks.com/api-reference/billing/cancel mint-openapi.yaml POST /v1/billing/cancel Cancel the active subscription for the authenticated tenant at the end of the current billing period. ```http theme={null} POST /v1/billing/cancel ``` Cancels your active subscription. The cancellation takes effect at the end of the current billing period — you retain full access until then. After the period ends, your account downgrades to the Developer (free) plan. ## Response Returns the updated subscription object with `cancel_at_period_end` set to `true`. **status** `string` Subscription status. Remains `active` until the period ends, then changes to `canceled`. **plan\_key** `string` The current plan identifier (e.g., `plan_starter`, `plan_business`). **current\_period\_end** `string` ISO 8601 timestamp for when the current billing period ends and the cancellation takes effect. **cancel\_at\_period\_end** `boolean` `true` after a successful cancellation request. > [!WARNING] > > Cancellation is immediate but takes effect at the end of your billing period. You cannot undo a cancellation via the API — to resubscribe, create a new [checkout session](/api-reference/billing/checkout). # Create checkout session Source: https://docs.truthlocks.com/api-reference/billing/checkout mint-openapi.yaml POST /v1/billing/checkout Initiate a payment session to upgrade or change your plan. ```http theme={null} POST /v1/billing/checkout ``` For a paid monthly plan, requests a hosted checkout from an available provider using the registered billing country. Usage-based business plans can instead return `activated: true` without a hosted checkout; they can still incur usage charges. Staff must approve the billing country before paid plans or usage-based business tiers are enabled. An unapproved country returns HTTP `409` with `code: BILLING_COUNTRY_REVIEW_REQUIRED`. Complete country review in the signed-in billing page first. Send a provider from the account's `visible_providers`. A URL parameter cannot change billing country. Existing paid personal subscriptions must be managed before starting another checkout. Flutterwave refuses monthly checkout if its recurring payment plan is missing. A checkout link is not proof of payment. Refresh the subscription after provider confirmation. ## Response **checkout\_url** `string` The hosted checkout page URL. Redirect the user to this URL to complete payment. # Get billing configuration Source: https://docs.truthlocks.com/api-reference/billing/config mint-openapi.yaml GET /v1/billing/config Returns the effective payment provider and current plan for the authenticated tenant. ```http theme={null} GET /v1/billing/config ``` Returns the payment provider routed for your region and your current plan. Use this to determine which checkout flow to present. ## Response **country\_code** `string` The country code used for provider routing. **effective\_provider** `string` The payment provider selected for this region (`stripe` or `flutterwave`; empty if unavailable). **visible\_providers** `string[]` All providers available in this region. **current\_plan** `string` The tenant's active plan key (for example, `plan_developer` or `plan_business`). **country\_verified** `boolean` Whether staff have approved the current billing country and no replacement review is pending. **country\_review\_required** `boolean` When true, country evidence must be approved before new paid billing can be enabled. The registered account country determines regional pricing and provider choices. A `country` query parameter does not override it. Provider choices depend on country and configuration; subscription checkout also requires the provider's recurring plan configuration. See [provider routing](/billing/provider-routing) for verification and payment limitations. # Get entitlements Source: https://docs.truthlocks.com/api-reference/billing/entitlements mint-openapi.yaml GET /v1/billing/entitlements Returns the current plan, feature flags, and usage quotas for the authenticated tenant. ```http theme={null} GET /v1/billing/entitlements ``` Returns the resolved entitlements for your tenant, including the active plan, unlocked feature flags, and numeric quotas. Use this to check what your current plan allows before performing billable operations. ## Response **plan\_key** `string` The active plan identifier (e.g., `plan_starter`, `plan_business`). **features** `object` Feature flags unlocked by your plan and add-ons. Each key is a feature name and the value indicates whether it is enabled. **online\_verification** `boolean` Whether online verification is enabled. **offline\_bundles** `boolean` Whether offline proof bundles are enabled. **sso\_scim** `boolean` Whether SSO and SCIM provisioning are enabled. **quotas** `object` Numeric limits for billable resources. Each key is a metric name and the value is the limit. **attestations.mint** `integer` Maximum attestation mints per billing cycle. **seats** `integer` Maximum team members. **api\_rate\_limit** `integer` API rate limit in requests per minute. **storage\_bytes** `integer` Maximum storage in bytes. **webhook\_endpoints** `integer` Maximum webhook endpoints. > [!NOTE] > > To check your active add-ons, see [billing overview](/billing/overview). Add-on entitlements are merged into the `features` and `quotas` objects automatically. # Estimate plan cost Source: https://docs.truthlocks.com/api-reference/billing/estimate mint-openapi.yaml POST /v1/billing/estimate Get a plan recommendation and estimated monthly cost based on your expected usage. ```http theme={null} POST /v1/billing/estimate ``` Returns a plan recommendation and estimated monthly cost based on your expected usage. This is a public endpoint — no authentication is required. Use it to help users choose the right plan during onboarding or on a pricing page. ## Response **recommended\_plan\_key** `string` The plan that best fits your requirements (e.g., `plan_starter`, `plan_business`). **recommended\_addons** `object[]` Add-ons the estimate suggests based on your needs (e.g., extra seats beyond the plan limit). **estimated\_monthly\_total** `number` Projected monthly cost in USD. **currency** `string` Currency code (`USD`). **assumptions** `string[]` Notes about the estimate (e.g., volume discounts, custom pricing). **provider\_routing** `object` Payment provider information for the given country. **default\_provider** `string` Default payment provider for the region. **visible\_providers** `string[]` All available providers in the region. > [!TIP] > > For a detailed line-item breakdown of costs, use the [projected invoice](/api-reference/billing/projected-invoice) endpoint instead. # List invoices Source: https://docs.truthlocks.com/api-reference/billing/invoices mint-openapi.yaml GET /v1/billing/invoices Returns a paginated list of invoices for the authenticated tenant. Returns invoices for the authenticated workspace. This handler does not implement `start` or `end` filters. For a date-filtered download, use [Accounting export](/api-reference/billing/accounting-export). Amounts and document links depend on the invoice record; do not assume all optional links are present. # List plans Source: https://docs.truthlocks.com/api-reference/billing/plans mint-openapi.yaml GET /v1/billing/plans Returns the available plan tiers with pricing, features, and quotas. ```http theme={null} GET /v1/billing/plans ``` Returns all available subscription plans. This is a public endpoint — no authentication is required. Use it for public price comparisons. When sending account authentication, the catalog uses that account’s saved billing country; its country query parameter cannot override the profile. ## Response Returns an array of plan objects in order from free to enterprise. **key** `string` Plan identifier used in checkout and subscription responses (e.g., `plan_developer`, `plan_business`). **name** `string` Human-readable plan name. **description** `string` Short description of the plan. **price** `number` Monthly base price in USD, including any applicable catalog regional adjustment. Fractional dollar amounts are possible. A zero monthly base price does not mean usage is free. **currency** `string` Currency code. Always `USD` for this catalog and current checkout implementation. **interval** `string` Billing interval. Always `month`. **features** `string[]` List of feature descriptions included in this plan. **highlight** `boolean` Whether this plan should be visually highlighted as the recommended option. > [!TIP] > > To check how much a specific usage pattern would cost, use the [plan estimator](/api-reference/billing/estimate) endpoint. # Open payment-method portal Source: https://docs.truthlocks.com/api-reference/billing/portal mint-openapi.yaml POST /v1/billing/portal Create a short-lived Stripe portal link for a signed-in billing account. Use this action from **Console → Settings → Billing → Payment methods** or your consumer billing page. It requires a signed-in human session. API keys cannot open a customer portal. Business workspaces require an active workspace administrator or a tenant-wide role with billing-management permission. For a usage-based workspace without a linked Stripe customer, the explicit portal request initializes and links that customer using the verified account email. Opening the portal does not charge a card, create a subscription, or change the plan. ## Request Set `provider` to `stripe` (the default). Flutterwave does not currently provide a self-service portal through this endpoint. Paystack is not supported here. Set `return_url` to an HTTPS address on `console.truthlocks.com` for a business session or `verify.truthlocks.com` for a consumer session. Other hosts are rejected. ## Response `portal_url` is a short-lived Stripe link. Open it to add or update payment details and view available Stripe invoices. Truthlocks' payment-method portal configuration does not enable subscription changes or cancellation; use the appropriate billing page for those actions. Treat this link as private and request a fresh one each time. ## Errors Errors return JSON with `code` and `error`. `403` means the signed-in person cannot manage this billing account. `422` identifies an unsupported provider. `502` or `503` indicates a provider or account-service failure; the message explains the next step. A failed account lookup does not create another provider customer. # Projected invoice Source: https://docs.truthlocks.com/api-reference/billing/projected-invoice mint-openapi.yaml POST /v1/billing/projected-invoice Calculate a projected invoice breakdown based on expected mint and verification volumes. ```http theme={null} POST /v1/billing/projected-invoice ``` Returns a line-item invoice projection based on the usage volumes you provide. Authentication is required. Use your workspace API key. Use it for pricing calculators, cost forecasting, or pre-sales tools. Regional pricing adjustments are applied when you include a `country_code`. This endpoint uses the standard rate card, not a tenant's negotiated agreement. Provide expected **billable** quantities; this calculator does not deduct free allowances or classify sandbox activity. Volume pricing is graduated. Each band prices only the operations in that band. The response identifies `billing_model: "pay_per_use"`, `volume_pricing: "graduated"`, `amount_unit: "cents"`, and `estimate_only: true`. An estimate does not create or charge an invoice. Missing, overlapping, or incomplete rate definitions return `422 invalid_pricing`; unsafe quantities and unknown plans return `400 bad_request`. The exact applied prices are in `line_items`. The convenience `rates_used` scalar fields are retained for compatibility with flat rate cards; they are not a blended price and must not be multiplied across volume bands. ## Response **line\_items** `object[]` Breakdown of projected charges. **description** `string` Line item description (e.g., "Credential mints"). **quantity** `integer` Number of units. **unit\_price\_cents** `integer` Per-unit price in cents. **total\_cents** `integer` Total cost for this line item in cents. **subtotal** `integer` Usage charges subtotal in cents (before platform fee). **total** `integer` Total projected cost in cents (usage + platform fee). **currency** `string` Rate-card currency code (currently `USD`). **rates\_used** `object` The rates applied to this projection. **mint\_rate\_cents** `integer` Per-mint rate in cents. **verify\_rate\_cents** `integer` Per-verification rate in cents. **platform\_fee** `integer` Monthly platform fee in cents. **region** `string` Pricing region tier applied. **multiplier** `number` Regional price multiplier. > [!NOTE] > > All amounts are in cents. Divide by 100 to convert to dollars. Regional multipliers apply automatically when you include a `country_code`. # Get rates Source: https://docs.truthlocks.com/api-reference/billing/rates mint-openapi.yaml GET /v1/billing/rates Returns the effective per-use rates for the authenticated tenant, including regional pricing adjustments. ```http theme={null} GET /v1/billing/rates ``` Returns your tenant's effective rate card, including per-use prices for minting and verification. If your organization has a custom rate card assigned by a platform admin, those rates are reflected here. Otherwise, the default rate card applies. Rates are automatically adjusted for your region based on your organization's country. ## Response **rate\_card** `object` The rate card metadata (ID, name, currency). **items** `object[]` Rate card line items with per-use pricing. **metric** `string` The billable metric (e.g., `attestations.mint`, `verifications`). **unit\_price** `integer` Base price in the smallest currency unit (cents for USD). **volume\_min** `integer` Minimum volume for tiered pricing. `0` for the base tier. **volume\_max** `integer` Maximum volume for this tier. `0` means no upper limit. **is\_default** `boolean` `true` if the default rate card is in use, `false` if a custom card has been assigned. **regional\_rates** `object` Adjusted rates for your region. **region** `string` Your pricing region tier. **multiplier** `number` The regional price multiplier applied to base rates. **mint\_rate\_cents** `integer` Effective per-mint rate in cents after regional adjustment. **verify\_rate\_cents** `integer` Effective per-verification rate in cents after regional adjustment. > [!TIP] > > For public pricing without authentication, use `GET /v1/billing/public/rates`. To estimate a monthly invoice, use the [projected invoice](/api-reference/billing/projected-invoice) endpoint. # Get billing status Source: https://docs.truthlocks.com/api-reference/billing/status mint-openapi.yaml GET /v1/billing/status Returns the current billing state, feature mode, and grace period for the authenticated tenant. ```http theme={null} GET /v1/billing/status ``` Returns your tenant's current billing health. Use this endpoint in your integration to detect payment issues early and surface prompts to your users before access is restricted. When all payments are current, `feature_mode` is `NORMAL` and `grace_until` is `null`. If a payment fails, the account enters a graduated access workflow — Degraded, Restricted, then Suspended — with a grace period at each stage. ## Response **status** `string` The billing account state: `ACTIVE`, `PAST_DUE`, `UNPAID`, or `SUSPENDED`. **feature\_mode** `string` The current feature capability level: * `NORMAL` — all features available * `DEGRADED` — payment failed; all features still work during the grace period * `RESTRICTED` — grace period running out; write operations (minting, key creation) are disabled * `SUSPENDED` — grace period expired; all API access is disabled until payment is resolved **grace\_until** `string | null` ISO 8601 timestamp for when the current grace period ends, or `null` if the account is in good standing. **banner** `string | null` A human-readable message describing the required action, or `null` when no action is needed. ## When to use this endpoint Use `GET /v1/billing/status` to: * **Surface payment prompts** — check `feature_mode` on app startup or login and show a banner when the value is anything other than `NORMAL`. * **Guard write operations** — before minting or creating keys, verify that `feature_mode` is not `RESTRICTED` or `SUSPENDED`. * **Track grace deadlines** — read `grace_until` to show your users exactly how long they have to resolve a payment issue. ```javascript theme={null} const res = await fetch("https://api.truthlocks.com/v1/billing/status", { headers: { "X-API-Key": "tl_live_..." }, }); const { feature_mode, grace_until } = await res.json(); if (feature_mode !== "NORMAL") { showPaymentBanner(feature_mode, grace_until); } ``` ## Grace period timing The default grace windows for the Standard contract mode are: | Transition | Grace window | Notifications | | :- | :- | :- | | NORMAL → DEGRADED | 7 days | Reminders at T+24h, T+48h, T+72h | | DEGRADED → RESTRICTED | 14 days | Reminders at T+24h, T+48h, T+72h | | RESTRICTED → SUSPENDED | Immediate | Final suspension notice | Enterprise contracts add 14 extra days to each window. Government contracts use a fixed 90-day grace period with no automatic suspension. See [contract modes](/billing/overview#contract-modes) for details. > [!TIP] > > See [payment failures and grace periods](/billing/overview#payment-failures-and-grace-periods) for a full breakdown of the graduated access workflow. # Get subscription Source: https://docs.truthlocks.com/api-reference/billing/subscription mint-openapi.yaml GET /v1/billing/subscription Returns the current subscription status and plan for the authenticated tenant. ```http theme={null} GET /v1/billing/subscription ``` Returns the active subscription for your tenant, including the current plan, billing status, and period end date. ## Response **status** `string` Subscription status: `active`, `past_due`, `canceled`, or `trialing`. **plan\_key** `string` The active plan identifier (e.g., `plan_starter`, `plan_business`). **current\_period\_end** `string` ISO 8601 timestamp for when the current billing period ends. **cancel\_at\_period\_end** `boolean` Whether the subscription is set to cancel at the end of the current period. > [!TIP] > > To see detailed usage counters for the current billing cycle, use the [usage endpoint](/api-reference/billing/usage). # Get usage Source: https://docs.truthlocks.com/api-reference/billing/usage mint-openapi.yaml GET /v1/billing/usage Returns current billing cycle usage counters for the authenticated tenant. ```http theme={null} GET /v1/billing/usage ``` Returns metered usage counters for the current billing period. Each counter tracks a billable resource and shows how much you have consumed relative to your plan limit. ## Response Returns an array of usage counter objects. **metric** `string` The usage metric identifier (e.g., `attestations.mint`, `verifications_monthly`, `storage_bytes`). **used** `integer` Amount consumed in the current billing period. **limit** `integer` Maximum allowed for this metric under your plan. A value of `-1` denotes no configured quota for this metric; service and rate limits still apply. **period** `string` Billing period for this counter: `monthly` or `total`. **unit** `string` Unit of measurement: `count` or `bytes`. **allowed** `boolean` Whether the tenant is currently allowed to consume more of this metric. Returns `false` when the limit has been reached. Only included when relevant. **delta** `integer` Change in usage since the last query. Only included when the server tracks incremental updates. ### Tracked metrics The usage endpoint returns up to 16 metrics organized by product group. Which metrics appear depends on your plan and active features. #### Core | Metric | Description | Unit | | - | - | - | | `attestations.mint` | Attestations minted | `count` | | `verifications_monthly` | Verifications performed | `count` | | `storage_bytes` | Total storage consumed | `bytes` | | `proof_bundles` | Proof bundles generated | `count` | | `webhook_endpoints` | Active webhook endpoints | `count` | | `webhook_deliveries` | Webhook deliveries sent | `count` | | `seats` | Team member seats | `count` | #### MAIP (Machine Identity) | Metric | Description | Unit | | - | - | - | | `maip.agents` | Registered machine agents | `count` | | `maip.sessions` | Agent sessions created | `count` | | `maip.trust_computes` | Trust score calculations | `count` | | `maip.compliance_checks` | Compliance verification requests | `count` | #### AI | Metric | Description | Unit | | - | - | - | | `ai.dataset_attestations` | Datasets attested for lineage | `count` | | `ai.model_attestations` | Models attested for provenance | `count` | #### Anti-Fraud | Metric | Description | Unit | | - | - | - | | `antifraud.risk_signals` | Risk signals ingested or generated | `count` | | `antifraud.deepfake_scans` | Deepfake scan requests | `count` | | `antifraud.velocity_records` | Velocity scoring records | `count` | > [!TIP] > > To check whether a specific operation is allowed before performing it, use the [entitlements endpoint](/api-reference/billing/entitlements) to verify your quotas. ## Console dashboard You can also view usage visually in the console at **Settings > Billing > Usage**. The dashboard shows all 16 metrics organized by product group (Core, MAIP, AI, and Anti-Fraud), each displayed as a progress bar against your plan limit. A projected monthly cost is calculated based on your current consumption and effective per-unit rates. # Accepted usage and monthly invoices Source: https://docs.truthlocks.com/api-reference/billing/usage-settlements mint-openapi.yaml GET /v1/billing/usage-settlements Read your workspace's accepted usage classifications and monthly invoice settlements. Requires authentication and returns only the caller's workspace records. This endpoint does not generate, approve, or pay invoices. `usage` contains up to 500 grouped records. Read `environment`, `classification`, `quantity`, `currency`, and `amount_cents` together. `rated` means the pricing snapshot was preserved at billing acceptance. Sandbox, free plans, consumer plans, approved pilots, and historical mint retries are excluded from business usage charges. Unresolved core pricing or environment evidence holds the month for staff review. `settlements` contains up to 200 monthly invoice records, newest first. A `DRAFT` is not payable. Staff must review the accepted commercial agreement, tax, and billing country before issue. `automatic_collection` is always `false` for this workflow: issuing an invoice does not charge a saved payment method. The UTC billing month uses acceptance time. Existing aggregate counters are not retroactively invoiced. Continue using the same mint idempotency key if a mint reports that its billing receipt could not be confirmed. Amounts ending in `_cents` are integer cents. The separately retrieved invoice uses currency units. For example, `amount_cents: 2500` corresponds to USD 25.00. # List machine compliance reports Source: https://docs.truthlocks.com/api-reference/compliance/reports mint-openapi.yaml GET /v1/compliance/reports List Compliance Reports Retrieve stored machine-identity compliance artifacts and apply the supported filters. These records are product evidence; they are not an independent SOC 2 report, ISO 27001 certificate or audit opinion. # Create consumer API key Source: https://docs.truthlocks.com/api-reference/consumer/api-keys/create mint-openapi.yaml POST /v1/consumer/api-keys Creates a new personal API key. The full secret is returned once and cannot be retrieved again. Consumers may hold up to 5 active keys. Keys expire after 90 days. Requires an authenticated individual consumer session; a business session or workspace API key cannot substitute for the user identity. Creates a new personal API key for the authenticated consumer. The full secret is returned **once** in the response and cannot be retrieved again — store it securely. Each consumer can hold up to **5 active keys**. Keys automatically expire after **90 days**. ### Responses # List consumer API keys Source: https://docs.truthlocks.com/api-reference/consumer/api-keys/list mint-openapi.yaml GET /v1/consumer/api-keys Returns all API keys for the authenticated consumer. Secrets are never returned in list responses. Requires an authenticated individual consumer session; a business session or workspace API key cannot substitute for the user identity. Returns all API keys belonging to the authenticated consumer. Secrets are never included in list responses — only the key prefix is shown. ### Responses # Revoke consumer API key Source: https://docs.truthlocks.com/api-reference/consumer/api-keys/revoke mint-openapi.yaml POST /v1/consumer/api-keys/{id}/revoke Permanently revokes a consumer API key. All requests using this key will immediately return 401. Permanently revokes a consumer API key. All requests using this key will immediately return `401 Unauthorized`. This action cannot be undone. ### Responses # Deliver to Consumer Inbox Source: https://docs.truthlocks.com/api-reference/consumer/deliver mint-openapi.yaml POST /v1/consumer/inbox/deliver Delivers an attestation to a consumer's inbox via email address. Requires API key (issuer-facing). Deliver an attestation to a consumer's inbox by email. If the consumer exists, the credential is delivered immediately. If the consumer hasn't signed up yet, the delivery is stored as pending and automatically claimed when they register. Requires issuer (tenant console) authentication. ### Responses # Consumer Inbox Source: https://docs.truthlocks.com/api-reference/consumer/inbox mint-openapi.yaml GET /v1/consumer/inbox Returns pending credential deliveries for the authenticated consumer. Requires an authenticated individual consumer session; a business session or workspace API key cannot substitute for the user identity. List inbox items for the authenticated consumer. Returns credentials that have been delivered to the consumer's wallet. Filter by read state to show unread, all, or archived items. ### Responses # Consumer Login Source: https://docs.truthlocks.com/api-reference/consumer/login mint-openapi.yaml POST /v1/consumer/login Authenticates a consumer and returns a session token. No API key required. Authenticate a consumer and receive a session cookie. The session cookie is HttpOnly and Secure. Consumers must verify their email before logging in. ### Responses # Protect Content (Consumer Mint) Source: https://docs.truthlocks.com/api-reference/consumer/mint mint-openapi.yaml POST /v1/consumer/mint Mint a cryptographic attestation for content you want to protect. Your personal issuer and signing key are resolved automatically. Hash the content client-side (SHA-256) and submit the hash with file metadata. Mint a cryptographic attestation for a piece of content you want to protect. Your personal issuer and signing key are resolved automatically — you do not need to create an issuer or register a key. Hash your content client-side with SHA-256 and submit the hash along with file metadata. The endpoint returns a protection record with a shareable proof URL you can use to demonstrate authorship. Rate limits depend on your plan tier: | Plan | Protections per month | | - | - | | Free | 50 | | Creator | 500 | | Pro | Plan-dependent | The response includes `content_hash` and `protected_at` so you can confirm which content was protected and the exact timestamp without making a follow-up call. ### Responses # Public Portfolio Source: https://docs.truthlocks.com/api-reference/consumer/portfolio mint-openapi.yaml GET /v1/consumer/portfolio/{username} Returns the public portfolio for a consumer by username. No authentication required. Retrieve a consumer's public portfolio by username. Returns all protections with visibility set to 'public'. No authentication required — this is a public endpoint for showcasing protected content. ### Responses # Request account deletion Source: https://docs.truthlocks.com/api-reference/consumer/privacy/delete-account mint-openapi.yaml POST /v1/consumer/privacy/delete-account Request permanent deletion of your account and all associated data. Deletion requests are processed within 30 days in compliance with data protection regulations. Request permanent deletion of your account and all associated data. This removes your profile, protections, credentials, signing keys, and activity history. Deletion requests are processed within 30 days in compliance with data protection regulations. You can continue using your account until processing begins. > [!WARNING] > > Account deletion is irreversible. All attestations, protections, and > credentials linked to your account will be permanently erased. Existing proof > pages and verification badges will stop resolving. ### Responses # Request data export Source: https://docs.truthlocks.com/api-reference/consumer/privacy/export mint-openapi.yaml POST /v1/consumer/privacy/export Request a full export of all data associated with your account. Exports are delivered in JSON format and include your profile, protections, credentials, and activity history. Request a full export of all data associated with your account. Exports are delivered in JSON format and include your profile, protections, credentials, and activity history. Processing typically completes within a few minutes. Once the export is ready, check the [list privacy jobs](/api-reference/consumer/privacy/jobs) endpoint or the [Privacy Center](https://verify.truthlocks.com/privacy) for a download link. ### Responses # List privacy jobs Source: https://docs.truthlocks.com/api-reference/consumer/privacy/jobs mint-openapi.yaml GET /v1/consumer/privacy/jobs List all privacy requests for the authenticated consumer. Returns export and deletion jobs sorted by creation date with real-time status updates. Requires an authenticated individual consumer session; a business session or workspace API key cannot substitute for the user identity. List all privacy requests for the authenticated consumer. Returns export and deletion jobs sorted by creation date (newest first), with real-time status updates. Use this endpoint to poll for export completion or check whether a deletion request has been processed. ### Responses ### Job statuses | Status | Meaning | | - | - | | `PENDING` | Request received, waiting to be processed | | `APPROVED` | Request approved and queued for execution | | `PROCESSING` | Actively being processed | | `COMPLETED` | Request fulfilled — download link available for exports | | `FAILED` | An error occurred; contact support | | `EXPIRED` | Export download link expired; request a new export | # Get consumer profile Source: https://docs.truthlocks.com/api-reference/consumer/profile mint-openapi.yaml GET /v1/consumer/me Returns the authenticated consumer's profile including name, email, MFA status, roles. Read the profile for the authenticated consumer. Use a consumer bearer token. See [Update profile](/api-reference/consumer/profile-update) to change preferences and [Claim username](/api-reference/consumer/username) to set a portfolio username. # Update consumer profile Source: https://docs.truthlocks.com/api-reference/consumer/profile-update mint-openapi.yaml PUT /v1/consumer/me Updates non-empty `name`, `region_code`, and `language` values. Names are limited to 200 characters. Supported region values are `US`, `EU`, `AF`, `GB`, `CA`, `AU`, and `SG`; supported languages are `en`, `es`, `fr`, `de`, and `zh`. Region is an account preference: setting it does not migrate existing data or provide a residency guarantee. Notification `settings` are not supported by this handler; submitting them returns HTTP 501 and leaves settings unchanged. Success returns `{"status":"updated"}`. # Get Proof Page Metadata Source: https://docs.truthlocks.com/api-reference/consumer/proof-metadata mint-openapi.yaml GET /v1/public/proof/{attestation_id} Returns metadata for a consumer content protection, used to render public proof pages. No authentication required. Returns metadata for a consumer content protection record. Use this endpoint to render proof pages that show what was protected, when, and by whom — without requiring authentication. This is a **public endpoint**. No API key or bearer token is needed. It is designed for proof page rendering and link previews (e.g. Open Graph metadata for shared proof URLs). ### Responses # List Protections Source: https://docs.truthlocks.com/api-reference/consumer/protections mint-openapi.yaml GET /v1/consumer/protections Returns all content protections (attestations) for the authenticated consumer. List all content protections for the authenticated consumer. Returns protections sorted by creation date (newest first), including attestation IDs, metadata, visibility status, and verification counts. ### Responses # Consumer Signup Source: https://docs.truthlocks.com/api-reference/consumer/signup mint-openapi.yaml POST /v1/consumer/signup Creates a new consumer account. No authentication required. Register a new consumer (B2C) account. Creates a personal tenant, organization, and user. The company\_name field is optional — if omitted, it defaults to the user's name + 's Workspace'. After signup, an email verification link is sent. Pending inbox deliveries (credentials minted before signup) are automatically claimed. ### Responses # Content similarity check Source: https://docs.truthlocks.com/api-reference/consumer/similarity mint-openapi.yaml GET /v1/consumer/similarity Check whether a content hash already has existing public protections. GET `/v1/consumer/similarity` Check whether a SHA-256 content hash already has public protections. This detects exact public hash matches; it does not perform perceptual or semantic similarity analysis or establish copyright ownership. Send an authenticated session using the authorization shown in Try It. Protections belonging to your workspace are excluded. The required `hash` query parameter is the SHA-256 digest you want to compare. Only protections with `visibility: "public"` are searched. Private protections are never returned. ### Responses ### Response fields | Field | Type | Description | | - | - | - | | `content_hash` | string | The hash you submitted, echoed back for confirmation. | | `exact_match` | boolean | `true` if at least one public protection exists for this hash. | | `matches` | array | Up to 10 matching protections, ordered by creation date. | | `matches[].attestation_id` | string | Attestation ID of the matching protection. | | `matches[].title` | string | Title of the matching protection. | | `matches[].category` | string | Content category (e.g. `photography`, `code`, `design`). | | `matches[].similarity_score` | number | Always `1.0` for exact hash matches. | | `matches[].protected_at` | string | ISO 8601 timestamp when the content was protected. | | `total` | integer | Number of returned matches, not an unbounded total. | # Consumer Stats Source: https://docs.truthlocks.com/api-reference/consumer/stats mint-openapi.yaml GET /v1/consumer/stats Returns statistics for the authenticated consumer's protections and portfolio. Retrieve content protection statistics for the authenticated consumer. Returns total protections, public protections count, and aggregate verification count. ### Responses # Update protection visibility Source: https://docs.truthlocks.com/api-reference/consumer/update-visibility mint-openapi.yaml PUT /v1/consumer/protections/{id}/visibility Toggle a content protection between public and private. PUT `/v1/consumer/protections/{id}/visibility` Change whether a content protection is publicly visible on your [portfolio](/guides/portfolio) or hidden. Public protections appear in [similarity checks](/api-reference/consumer/similarity) and on your public profile page. Private protections are only visible to you. You can only update visibility for your own protections. ### Responses # Claim a portfolio username Source: https://docs.truthlocks.com/api-reference/consumer/username mint-openapi.yaml PUT /v1/consumer/me/username Claims a unique username for the signed-in consumer. Use a valid lowercase username and handle a conflict if it is already assigned. Claiming a username does not automatically publish private protections; portfolio visibility is controlled separately. # Approve Issuer Request Source: https://docs.truthlocks.com/api-reference/governance/approve mint-openapi.yaml POST /v1/governance/issuer-requests/{requestId}/approve Marks a governance request as approved. Approves a pending issuer governance request. This is part of the enterprise governance workflow. Requires governance:approve permission. ### Responses # Create governance request Source: https://docs.truthlocks.com/api-reference/governance/create-request mint-openapi.yaml POST /v1/governance/issuer-requests Creates a new governance request for issuer approval/changes. Creates an issuer-change request for later review. Authenticate as a user with `GOVERNANCE_ADMIN` or `TENANT_ADMIN`; an API key alone does not supply the required user identity. Use `request_type`, `issuer_id`, `justification`, `proposed_changes`, and optional `evidence`. The old names `type`, `target_issuer_id`, and `reason` are not this request contract. The server assigns request identity, workspace, requester, status, and approval count. Creating a request does not execute it or bypass required approvals. # Execute Governance Request Source: https://docs.truthlocks.com/api-reference/governance/execute mint-openapi.yaml POST /v1/governance/issuer-requests/{requestId}/execute Executes a previously approved governance request. Executes a previously approved governance request. The request must have received all required approvals before it can be executed. Once executed, the action (suspend, revoke, reinstate) is applied to the target issuer. ### Responses # Read an issuer governance request Source: https://docs.truthlocks.com/api-reference/governance/get-request mint-openapi.yaml GET /v1/governance/issuer-requests/{requestId} Get issuer governance request Use the request identifier returned when proposing the change. Review the request status and approvals before execution; retrieving it does not approve or execute it. # List Governance Requests Source: https://docs.truthlocks.com/api-reference/governance/list-requests mint-openapi.yaml GET /v1/governance/issuer-requests Lists governance requests for issuer approval workflows. List all governance requests in the current tenant. Governance requests represent formal actions such as approving, suspending, or reinstating an issuer and may require multi-party approval. ### Responses # Health Check Source: https://docs.truthlocks.com/api-reference/health/check mint-openapi.yaml GET /healthz Returns service health status. No authentication required. Simple liveness probe that returns 200 OK if the service is running. Used by load balancers and orchestrators. ### Responses # Readiness Probe Source: https://docs.truthlocks.com/api-reference/health/ready mint-openapi.yaml GET /readyz Returns service readiness. No authentication required. Detailed health check that verifies connectivity to upstream dependencies like Postgres, Redis, and NATS. ### Responses # Programmatic status Source: https://docs.truthlocks.com/api-reference/health/status mint-openapi.yaml GET /api/health Query real-time service health for all Truthlocks services. No authentication required. Returns the current health status of every Truthlocks service. Use this endpoint to integrate service availability into your own dashboards, alerting pipelines, or circuit breakers. This endpoint is served from `status.truthlocks.com`, not the main API. No authentication is required. ```http theme={null} GET https://status.truthlocks.com/api/health ``` ### Response fields | Field | Type | Description | | - | - | - | | `status` | string | Overall system health: `operational`, `degraded`, or `outage`. | | `timestamp` | string | ISO 8601 timestamp of the check. | | `services` | array | Per-service health results. | | `services[].id` | string | Machine-readable service identifier (e.g., `api-gateway`, `signing-service`). | | `services[].name` | string | Human-readable service name. | | `services[].status` | string | Service health: `operational`, `degraded`, or `outage`. | | `services[].responseTime` | number or null | Response time in milliseconds, or `null` if unreachable. | | `services[].error` | string | Present only when the service is not operational. Describes the failure reason. | ### Status logic * **`operational`** — all services are healthy and responding normally. * **`degraded`** — at least one service is slow or returning errors, but none are fully down. * **`outage`** — at least one service is completely unreachable. ### Monitored services | Service ID | Name | Description | | - | - | - | | `api-gateway` | API Gateway | Main API endpoint for all public requests | | `trust-registry` | Trust Registry | Issuer management and governance | | `billing-service` | Billing | Subscription and payment processing | | `signing-service` | Signing | Cryptographic signing operations | | `attestation-service` | Attestations | Attestation minting and management | | `audit-service` | Audit Logs | Activity logging and compliance | | `transparency-log` | Transparency Log | Cryptographic append-only log | | `verification-service` | Verification | Proof bundle verification | ### Example: poll status from your application ```javascript theme={null} async function checkTruthlockStatus() { const res = await fetch("https://status.truthlocks.com/api/health"); const data = await res.json(); if (data.status !== "operational") { console.warn(`Truthlocks is ${data.status}`); const issues = data.services.filter((s) => s.status !== "operational"); issues.forEach((s) => console.warn(` ${s.name}: ${s.status} — ${s.error}`) ); } return data; } ``` ### Example: pre-flight check before minting ```javascript theme={null} async function mintWithStatusCheck(attestation) { const status = await fetch("https://status.truthlocks.com/api/health"); const health = await status.json(); const signingService = health.services.find( (s) => s.id === "signing-service" ); const attestationService = health.services.find( (s) => s.id === "attestation-service" ); if ( signingService?.status !== "operational" || attestationService?.status !== "operational" ) { throw new Error("Required services are not operational — retry later"); } return client.attestations.mint(attestation); } ``` > [!NOTE] > > This endpoint is rate-limited to prevent abuse. For continuous monitoring, poll > no more frequently than once every 30 seconds. # Assign role Source: https://docs.truthlocks.com/api-reference/identity/assign-role mint-openapi.yaml POST /v1/role-bindings Bind a role to a user within your tenant. Assigns a role to a user by creating a role binding. You can scope the binding to the entire tenant or to a specific organization within the tenant. ### Responses # Create custom role Source: https://docs.truthlocks.com/api-reference/identity/create-role mint-openapi.yaml POST /v1/roles Create a custom role with a name and description for your tenant. Creates a new custom role within your tenant. Custom roles let you define access permissions tailored to your team structure. After creating a role, assign it to users with the [assign role](/api-reference/identity/assign-role) endpoint. See [RBAC & permissions](/security/rbac) for the full list of available permissions and guidance on role design. ### Responses # List Organizations Source: https://docs.truthlocks.com/api-reference/identity/orgs mint-openapi.yaml GET /v1/orgs Returns organizations for the authenticated tenant. Returns a list of organizations associated with the authenticated tenant. This endpoint is typically used by workspace administrators to manage tenant structure. ### Responses # Get Organization Source: https://docs.truthlocks.com/api-reference/identity/orgs/get mint-openapi.yaml GET /v1/orgs/{id} Returns details for a specific organization. Returns detailed information about a specific organization. Includes status, branding settings, and member counts. ### Responses # Manage Roles Source: https://docs.truthlocks.com/api-reference/identity/roles mint-openapi.yaml GET /v1/roles Returns available roles for the organization. Returns a list of all available roles and their associated permissions within the tenant. Used for RBAC configuration. ### Responses # Create application Source: https://docs.truthlocks.com/api-reference/issuer-applications/create mint-openapi.yaml POST /v1/issuer-applications Create a new issuer application in draft status. Creates a new issuer application for your organization. The application starts in `DRAFT` status, allowing you to upload evidence before submitting for review. See the [issuer application guide](/guides/issuer-applications) for a walkthrough of the full application workflow. ### Responses # Get application Source: https://docs.truthlocks.com/api-reference/issuer-applications/get mint-openapi.yaml GET /v1/issuer-applications/{id} Retrieve a single issuer application with its evidence and review history. Returns the full details of an issuer application, including uploaded evidence documents and the complete review action timeline. ### Responses # List applications Source: https://docs.truthlocks.com/api-reference/issuer-applications/list mint-openapi.yaml GET /v1/issuer-applications List issuer applications for your tenant with optional status filtering. Returns a paginated list of issuer applications belonging to your tenant. Use the `status` query parameter to filter by application state. ### Responses # Submit application Source: https://docs.truthlocks.com/api-reference/issuer-applications/submit mint-openapi.yaml POST /v1/issuer-applications/{id}/submit Submit a draft issuer application for platform review. Moves an issuer application from `DRAFT` to `SUBMITTED` status and triggers a notification to the platform review team. Only applications in `DRAFT` status can be submitted. After submission, you cannot modify the application or upload additional evidence unless the reviewer requests changes. ### Responses # Create Issuer Source: https://docs.truthlocks.com/api-reference/issuers/create mint-openapi.yaml POST /v1/issuers Registers a new issuer. Newly created issuers start in PENDING status. Registers a new issuer in the trust registry. Newly created issuers are activated immediately and can start minting attestations right away. To request a higher trust tier, submit an [issuer application](/guides/issuer-applications) for review. ### Responses # List Issuer Events Source: https://docs.truthlocks.com/api-reference/issuers/events mint-openapi.yaml GET /v1/issuers/{id}/events Returns the event history for a specific issuer. Returns a timeline of all lifecycle events for a specific issuer, including trust changes, key rotations, suspensions, and governance actions. ### Responses # Get Issuer Source: https://docs.truthlocks.com/api-reference/issuers/get mint-openapi.yaml GET /v1/issuers/{id} Returns details for a specific issuer. Retrieves details of a specific issuer by their unique ID. ### Responses # Create or Register an Issuer Key Source: https://docs.truthlocks.com/api-reference/issuers/keys mint-openapi.yaml POST /v1/issuers/{id}/keys Creates a dedicated managed key or registers an external public verification key. Managed generation supports Ed25519, ES256, ES384, RS256, RS512, PS256 and PS512. Import additionally supports ES512, RS384 and PS384; importing a public key does not enable server-side minting. Creates a managed key or registers public-key material for the issuer identified by path parameter `id`. ## Managed signing Use `provider: "KMS"` and the desired `alg`. Managed generation supports **Ed25519, ES256, ES384, RS256, RS512, PS256 and PS512**. See [algorithm support and encoding](/enterprise/signing-algorithms). Use the generated `kid` returned in the response; an arbitrary requested key ID is not retained in this mode. ```json theme={null} {"provider": "KMS", "alg": "Ed25519"} ``` Algorithm availability depends on the deployed provider. An algorithm name alone does not establish compliance with an industry or government standard. ## Public-key registration Import mode requires `kid`, `alg`, and `public_key_b64url`. `algorithm` and `public_key` are not substitutes. Encode the DER SubjectPublicKeyInfo public-key bytes as unpadded base64url. Registering a public key does **not** provision its private key, and is insufficient by itself for server-side minting. Never send private-key material in this request. The response includes `issuer_id`, `kid`, `alg`, `public_key_b64url`, `provider`, and `created_at`. Confirm signing availability before minting. # Report Key Compromise Source: https://docs.truthlocks.com/api-reference/issuers/keys-compromise mint-openapi.yaml POST /v1/issuers/keys/{kid}/compromise Reports a key as compromised. Immediately disables the key and flags all attestations signed with it for review. Reports a signing key as compromised. This immediately disables the key and marks all attestations signed by this key as requiring re-verification. This action is irreversible. ### Responses # Rotate Key Source: https://docs.truthlocks.com/api-reference/issuers/keys-rotate mint-openapi.yaml POST /v1/issuers/keys/{kid}/rotate Creates a replacement key in the same issuer and environment, and expires the old key for new issuance. Stored records issued before the cutoff retain verification support unless the key is compromised or revoked. Managed generation supports Ed25519, ES256, ES384, RS256, RS512, PS256 and PS512. Creates a replacement key for an active key and atomically expires the old key for new issuance. The replacement stays in the same issuer and environment. Use its returned `kid` explicitly in subsequent mint requests; callers are not silently switched to another key. ## Generate a replacement ```json theme={null} {"provider": "KMS", "alg": "ES256"} ``` Managed generation supports Ed25519, ES256, ES384, RS256, RS512, PS256 and PS512. For public-key import, supply `kid`, `alg` and `public_key_b64url` with DER SubjectPublicKeyInfo encoded as unpadded base64url. Imported public material alone cannot mint new records. See [signing algorithms](/enterprise/signing-algorithms). ## Existing records Verification uses the registered issuance timestamp. Records issued before the old key's cutoff can still pass signature verification with their original payload. A compromised or revoked key is rejected even for older records. Missing trusted timestamps cannot be replaced with a caller-supplied date. Success returns HTTP **201** with the replacement key and `rotated_from`. A retired key cannot be rotated again. Record expiry, revocation and signature checks continue to apply independently. # List Issuers Source: https://docs.truthlocks.com/api-reference/issuers/list mint-openapi.yaml GET /v1/issuers Returns all issuers for the authenticated tenant. Returns all issuers for the authenticated tenant. Includes issuer status, trust level, and key count. ### Responses # List issuer signing keys Source: https://docs.truthlocks.com/api-reference/issuers/list-keys mint-openapi.yaml GET /v1/issuers/{id}/keys List Issuer Keys Use an issuer ID from your workspace. This returns registered public key metadata and lifecycle state; it does not return private signing material. An expired key can still verify historical records issued during its validity period. # Get Agent Source: https://docs.truthlocks.com/api-reference/machine-identity/agents/get mint-openapi.yaml GET /v1/agents/{agentId} Retrieve full details for a specific machine agent identity # Get Agent `GET /v1/agents/{agentID}` Returns the complete agent identity record for the specified agent, including cryptographic key information, current trust score, assigned scopes, delegation depth, and all metadata. The agent must belong to the authenticated tenant. ### Authentication Requires `X-API-Key` header or Bearer JWT token. The workspace is derived from the authenticated credential; do not send `X-Tenant-ID`. ### Response **id** `string` Internal UUID primary key. **agent\_id** `string` MAIP-compliant agent identifier. **tenant\_id** `string` UUID of the owning tenant. **agent\_type** `string` Agent type classification. **display\_name** `string` Human-readable agent name. **description** `string` Agent description. **trust\_level** `string` Trust hierarchy level. One of: `"platform_root"`, `"verified_org"`, `"verified_individual"`, `"authenticated"`, `"self_asserted"`, `"anonymous"`. **trust\_score** `number` Numeric trust score between 0.0 and 1.0. Adjusted over time based on agent behavior, anomaly detection, and attestation history. **status** `string` Current lifecycle status: `"active"`, `"suspended"`, or `"revoked"`. **public\_key** `string` Base64url-encoded Ed25519 public key for this agent. **key\_id** `string` Unique key identifier for receipt and attestation signature verification. **scopes** `string[]` Assigned permission scopes in `resource:action` format. **metadata** `object` Arbitrary metadata attached to the agent. **parent\_agent\_id** `string` If this agent was created via delegation, the parent agent's MAIP ID. **delegation\_depth** `number` Position in the delegation chain (0 = root, max 8). **created\_by\_user\_id** `string` UUID of the user who registered the agent, if applicable. **compromised\_at** `string` ISO 8601 timestamp if the agent's key was marked compromised. **expires\_at** `string` Automatic expiration timestamp, if configured. **created\_at** `string` ISO 8601 creation timestamp. **updated\_at** `string` ISO 8601 last-updated timestamp. ### Example ```bash theme={null} curl https://api.truthlocks.com/v1/agents/maip:t1234567:01HYX3KPZQ7RJGBN0WFMV8SDEH \ -H "X-API-Key: tl_live_..." ``` # List Agents Source: https://docs.truthlocks.com/api-reference/machine-identity/agents/list mint-openapi.yaml GET /v1/agents List all machine agent identities for the authenticated tenant with filtering and pagination # List Agents `GET /v1/agents` Returns a paginated list of all machine agent identities registered under the authenticated tenant. Results can be filtered by agent type, status, and trust level. Agents are returned in reverse chronological order (newest first). ### Authentication Requires `X-API-Key` header or Bearer JWT token. The workspace is derived from the authenticated credential; do not send `X-Tenant-ID`. ### Response **agents** `object[]` Array of agent identity objects. Each object contains the full agent record including `agent_id`, `agent_type`, `display_name`, `status`, `trust_level`, `trust_score`, `scopes`, `public_key`, `key_id`, `metadata`, `delegation_depth`, `created_at`, and `updated_at`. **total** `integer` Total count of agents matching the filter criteria, across all pages. ### Example ```bash theme={null} curl -G https://api.truthlocks.com/v1/agents \ -H "X-API-Key: tl_live_..." \ -d "status=active" \ -d "agent_type=llm" \ -d "limit=10" \ -d "offset=0" ``` # Register Agent Source: https://docs.truthlocks.com/api-reference/machine-identity/agents/register mint-openapi.yaml POST /v1/agents Register a new machine agent identity with cryptographic key pair and scoped permissions # Register Agent `POST /v1/agents` Registers a new machine agent identity for the authenticated tenant. The platform generates an Ed25519 key pair for the agent, assigns a MAIP-compliant agent ID, and records the initial key in the key history ledger. Newly registered agents start with `active` status and an initial trust score of `0.500`. > [!NOTE] > > The number of agents you can register depends on your billing plan. If you > exceed your plan limit, the API returns `402 Payment Required`. Contact sales > for enterprise-tier agent limits. ### Authentication Requires `X-API-Key` header or Bearer JWT token. The workspace is derived from the authenticated credential; do not send `X-Tenant-ID`. ### Response **id** `string` Internal UUID primary key. **agent\_id** `string` MAIP-compliant agent identifier in format `maip::`. Use this value in all subsequent API calls referencing this agent. **tenant\_id** `string` UUID of the owning tenant. **agent\_type** `string` The registered agent type. **display\_name** `string` Human-readable agent name. **description** `string` Agent description, if provided. **trust\_level** `string` Initial trust level. Newly registered agents start at `"authenticated"`. **trust\_score** `number` Numeric trust score (0.0 to 1.0). Newly registered agents start at `0.500`. **status** `string` Agent lifecycle status. Always `"active"` on creation. **public\_key** `string` Base64url-encoded Ed25519 public key generated for this agent. Store this securely for signature verification. **key\_id** `string` Unique identifier for the agent's signing key. Referenced in receipts and attestations. **scopes** `string[]` The effective scopes assigned to the agent. **metadata** `object` The metadata object, if provided. **delegation\_depth** `number` Current delegation chain depth. Always `0` for directly registered agents. Maximum depth is `8` per MAIP protocol. **created\_by\_user\_id** `string` UUID of the user who registered the agent, if authenticated via user token. **expires\_at** `string` Expiration timestamp, if set. **created\_at** `string` ISO 8601 creation timestamp. **updated\_at** `string` ISO 8601 last-updated timestamp. ### Example ```bash theme={null} curl -X POST https://api.truthlocks.com/v1/agents \ -H "X-API-Key: tl_live_..." \ -H "Content-Type: application/json" \ -d '{ "agent_type": "llm", "display_name": "Customer Support Bot", "description": "Handles Tier-1 customer support inquiries via chat", "scopes": ["data:read", "tool:search.web", "!data:delete"], "metadata": { "team": "support", "model": "claude-3.5-sonnet", "environment": "production" } }' ``` # Revoke Agent Source: https://docs.truthlocks.com/api-reference/machine-identity/agents/revoke mint-openapi.yaml POST /v1/agents/{agentId}/revoke Permanently revoke a machine agent identity, terminating all sessions and blocking future operations # Revoke Agent `POST /v1/agents/{agentID}/revoke` Permanently revokes a machine agent identity. This is an irreversible operation that: 1. Sets the agent status to `"revoked"` 2. Invalidates all active sessions 3. Blocks all future tool invocations 4. Prevents the agent from being used in new delegations > [!WARNING] > > Revocation is **permanent and cannot be undone**. If you need to temporarily > disable an agent, use the [suspend > endpoint](/api-reference/machine-identity/agents/suspend) instead. Revoked > agents remain in the system for audit trail purposes but cannot be > reactivated. ### Authentication Requires `X-API-Key` header or Bearer JWT token. The workspace is derived from the authenticated credential; do not send `X-Tenant-ID`. ### Response **status** `string` Updated status, always `"revoked"` on success. **agent\_id** `string` The MAIP agent identifier that was revoked. ### Example ```bash theme={null} curl -X POST https://api.truthlocks.com/v1/agents/maip:t1234567:01HYX3KPZQ7RJGBN0WFMV8SDEH/revoke \ -H "X-API-Key: tl_live_..." \ -H "Content-Type: application/json" \ -d '{ "reason": "Agent key compromised. Security incident SI-2026-0412. Replacement agent registered as maip:t1234567:01HYX9NPZS0TMHDO2YHOU0UFGJ." }' ``` *** ### When to Revoke vs. Suspend | Scenario | Action | | - | - | | Anomalous behavior detected, investigation pending | [Suspend](/api-reference/machine-identity/agents/suspend) | | Temporary maintenance or configuration change | [Suspend](/api-reference/machine-identity/agents/suspend) | | Agent key confirmed compromised | **Revoke** | | Agent decommissioned from production | **Revoke** | | Compliance or legal hold requires permanent disablement | **Revoke** | > [!NOTE] > > After revoking an agent, you can still view its full history via the [GET > /v1/agents/](/api-reference/machine-identity/agents/get) endpoint. > The agent record is retained indefinitely for audit compliance (SOC 2 Type II, > ISO 27001). # Suspend Agent Source: https://docs.truthlocks.com/api-reference/machine-identity/agents/suspend mint-openapi.yaml POST /v1/agents/{agentId}/suspend Temporarily suspend a machine agent, blocking all sessions and tool invocations # Suspend Agent `POST /v1/agents/{agentID}/suspend` Suspends a machine agent identity, immediately preventing it from creating new sessions, invoking tools, or performing any authenticated operations. Suspension is reversible -- the agent can be reactivated by updating its status back to `"active"` via the [update endpoint](/api-reference/machine-identity/agents/update). All active sessions belonging to the suspended agent are effectively blocked at the access-control layer. Existing session tokens will fail scope checks until the agent is reactivated. > [!NOTE] > > Suspension is the recommended first response for anomalous agent behavior. Use > [revoke](/api-reference/machine-identity/agents/revoke) only when permanent > decommissioning is required. ### Authentication Requires `X-API-Key` header or Bearer JWT token. The workspace is derived from the authenticated credential; do not send `X-Tenant-ID`. ### Response **status** `string` Updated status, always `"suspended"` on success. **agent\_id** `string` The MAIP agent identifier that was suspended. ### Example ```bash theme={null} curl -X POST https://api.truthlocks.com/v1/agents/maip:t1234567:01HYX3KPZQ7RJGBN0WFMV8SDEH/suspend \ -H "X-API-Key: tl_live_..." \ -H "Content-Type: application/json" \ -d '{ "reason": "Anomalous data access pattern detected by velocity scoring at 2026-04-06T15:00:00Z" }' ``` *** ### Reactivating a Suspended Agent To restore a suspended agent to active status, use the [PATCH /v1/agents/](/api-reference/machine-identity/agents/update) endpoint: ```bash theme={null} curl -X PATCH https://api.truthlocks.com/v1/agents/maip:t1234567:01HYX3KPZQ7RJGBN0WFMV8SDEH \ -H "X-API-Key: tl_live_..." \ -H "Content-Type: application/json" \ -d '{"status": "active"}' ``` # Update Agent Source: https://docs.truthlocks.com/api-reference/machine-identity/agents/update mint-openapi.yaml PATCH /v1/agents/{agentId} Update an agent's display name, description, metadata, or status # Update Agent `PATCH /v1/agents/{agentID}` Updates mutable fields on an existing machine agent identity. Only the fields provided in the request body are modified; all other fields remain unchanged. At least one field must be provided. > [!WARNING] > > To change an agent's scopes, use the delegation system or re-register the > agent. Scopes cannot be modified directly through this endpoint to preserve > the audit trail of scope changes. ### Authentication Requires `X-API-Key` header or Bearer JWT token. The workspace is derived from the authenticated credential; do not send `X-Tenant-ID`. ### Request Body All fields are optional, but at least one must be provided. ### Response Returns the full updated agent identity object. **id** `string` Internal UUID primary key. **agent\_id** `string` MAIP-compliant agent identifier. **display\_name** `string` The updated display name. **description** `string` The updated description. **metadata** `object` The updated metadata object. **status** `string` Current lifecycle status after update. **updated\_at** `string` ISO 8601 timestamp reflecting the update. ### Example ```bash theme={null} curl -X PATCH https://api.truthlocks.com/v1/agents/maip:t1234567:01HYX3KPZQ7RJGBN0WFMV8SDEH \ -H "X-API-Key: tl_live_..." \ -H "Content-Type: application/json" \ -d '{ "display_name": "Customer Support Bot v2", "description": "Upgraded to handle Tier-1 and Tier-2 support with escalation", "metadata": { "team": "support", "model": "claude-opus-4", "environment": "production", "version": "2.0" } }' ``` # Report Anomaly Source: https://docs.truthlocks.com/api-reference/machine-identity/anomalies/report mint-openapi.yaml POST /v1/agents/{agentId}/anomalies Report a behavioral anomaly detected in an AI agent's activity. Reports a behavioral anomaly detected in an AI agent's activity. Anomalies are flagged observations that indicate an agent may be operating outside its expected behavioral envelope -- such as sudden rate spikes, scope violations, trust score drops, or geographic access anomalies. Anomaly reports create actionable alerts for security teams and can trigger automated response policies (e.g., throttling, session revocation, or agent suspension) depending on severity and tenant configuration. ### Anomaly Types | Type | Description | | :- | :- | | `rate_spike` | Agent's request rate significantly exceeds historical baseline | | `scope_violation` | Agent attempted to access a resource outside its granted scopes | | `trust_drop` | Agent's computed trust score dropped below threshold | | `pattern_deviation` | Agent's behavioral pattern deviates from its trained baseline | | `geographic_anomaly` | Agent accessed from an unexpected geographic location or IP range | ### Severity Levels | Severity | SLA | Auto-Response | | :- | :- | :- | | `low` | 24h review | Logged only | | `medium` | 4h review | Agent throttled | | `high` | 1h review | Sessions suspended | | `critical` | 15min review | Agent revoked pending investigation | ### Response **id** `string` Unique anomaly identifier in MAIP format (`maip-anom:ULID`). **agent\_id** `string` The agent associated with the anomaly. **anomaly\_type** `string` Type of anomaly reported. **severity** `string` Severity level. **status** `string` Anomaly status. Always `open` on creation. **auto\_response** `string` Automated response action taken (if any), based on severity and tenant policy. **created\_at** `string` ISO 8601 timestamp of creation. # Resolve an anomaly Source: https://docs.truthlocks.com/api-reference/machine-identity/anomalies/resolve mint-openapi.yaml POST /v1/agents/{agentId}/anomalies/{anomalyId}/resolve Marks an anomaly as resolved with a resolution description. Marks the identified anomaly resolved. The anomaly ID is a UUID. No JSON body is consumed by the current handler; `resolution` and `notes` are not recorded by this endpoint. The response contains `status: resolved` and `anomaly_id`. Resolution does not automatically restore, revoke, or otherwise change the agent. Use the relevant agent operation for a separate authorized status change. # Create Compliance Check Source: https://docs.truthlocks.com/api-reference/machine-identity/compliance/create-check mint-openapi.yaml POST /v1/compliance/check Run an automated compliance check against a regulation for an entity Executes an automated compliance assessment for a specific entity (agent, model, dataset, or workflow) against a supported regulation. The check evaluates the entity's configuration, access patterns, data handling, and audit trail against the regulation's requirements and produces a compliance determination with detailed findings. Compliance checks are idempotent for the same entity-regulation pair within a 24-hour window. Repeated calls within that window return the cached result. ### Authentication Requires `X-API-Key` header or Bearer JWT token. The workspace is derived from the authenticated credential; do not send `X-Tenant-ID`. ### Response **id** `string` Unique identifier for the compliance check record. Format: `maip-cc:ULID`. **entity\_type** `string` The type of entity that was assessed. **entity\_id** `string` The identifier of the assessed entity. **regulation** `string` The regulation that was assessed. **scope** `string` The scope of the assessment. `full` if no scope was specified. **status** `string` The compliance determination. One of: - `compliant` -- entity meets all assessed requirements - `non_compliant` -- entity fails one or more critical requirements - `partial` -- entity meets some but not all requirements **findings** `object[]` Detailed list of individual findings from the assessment. **Finding fields** **findings\[].control\_id** `string` The control identifier within the regulation (e.g., `CC6.1` for SOC2, `A.9.1.1` for ISO27001). **findings\[].control\_name** `string` Human-readable name of the control. **findings\[].status** `string` Status of this specific control: `pass`, `fail`, `partial`, `not_applicable`. **findings\[].severity** `string` Severity of the finding if not passing: `critical`, `high`, `medium`, `low`. **findings\[].description** `string` Detailed description of the finding and remediation guidance. **receipt\_id** `string` The MAIP receipt minted for this compliance check, providing an immutable audit record. **checked\_at** `string` ISO 8601 timestamp of when the assessment was performed. ### Supported Regulations | Regulation | Controls Assessed | Typical Duration | | :- | :- | :- | | `SOC2` | Trust Service Criteria (CC1-CC9) | 2-5 seconds | | `ISO27001` | Annex A controls (A.5-A.18) | 2-5 seconds | | `GDPR` | Articles 5, 6, 12-22, 25, 32-34 | 3-8 seconds | | `HIPAA` | Administrative, Physical, Technical Safeguards | 3-8 seconds | | `EU_AI_ACT` | Risk classification, transparency, human oversight | 5-10 seconds | # Generate a compliance report Source: https://docs.truthlocks.com/api-reference/machine-identity/compliance/reports mint-openapi.yaml POST /v1/compliance/reports Aggregates recorded compliance checks for an entity and period. Supply `entity_id`, `regulation`, `period_start`, and `period_end`; `entity_type` defaults to `agent`. Periods use date-time values and the end must not precede the start. Requires a signed-in user bearer token. The server derives the reviewer identity. The handler returns synchronously; it does not switch to a background report job for long periods. A report summarizes stored check results, not independent regulatory certification. Generated report receipts currently use system markers rather than cryptographic signatures. # Attest Dataset Source: https://docs.truthlocks.com/api-reference/machine-identity/datasets/attest mint-openapi.yaml POST /v1/datasets/attest Create a provenance and integrity attestation for a dataset used by AI agents. Creates a cryptographically anchored attestation for a dataset, recording its provenance, integrity hash, and schema version. The attestation is linked to the originating agent and anchored in the transparency log for full auditability. Dataset attestations enable downstream consumers to verify that training data, evaluation sets, or inference inputs have not been tampered with and can be traced back to a known source. ### Response **id** `string` Unique dataset attestation identifier in MAIP format (`maip-ds:ULID`). **agent\_id** `string` The agent that attested this dataset. **name** `string` Dataset name as provided in the request. **version** `string` Resolved version of the dataset. **hash** `string` SHA-256 hex digest stored for integrity verification. **status** `string` Attestation status. Always `attested` on creation. **receipt\_id** `string` Transparency-log receipt anchoring this attestation. **created\_at** `string` ISO 8601 timestamp of creation. # Get Dataset Lineage Source: https://docs.truthlocks.com/api-reference/machine-identity/datasets/lineage mint-openapi.yaml GET /v1/datasets/lineage/{datasetId} Retrieve the full lineage graph for a dataset, including upstream sources and downstream consumers. Returns the complete lineage graph for a dataset attestation. The graph represents the provenance chain as a directed acyclic graph (DAG) of dataset and model references connected by transformation relationships. Use dataset lineage to audit data provenance, verify that training data sources are trusted, and trace how raw data flows through preprocessing pipelines into model training. ### Response **dataset\_id** `string` The root dataset identifier for this lineage query. **nodes** `array` Array of lineage nodes. Each node contains: - `id` (string) -- Resource identifier (`maip-ds:...` or `maip-model:...`) - `type` (string) -- Node type: `dataset` or `model` - `name` (string) -- Human-readable name - `version` (string) -- Resource version - `status` (string) -- Current attestation status * `created_at` (string) -- ISO 8601 timestamp **edges** `array` Array of transformation relationships connecting nodes. Each edge contains: - `source` (string) -- Source node identifier - `target` (string) -- Target node identifier - `relationship` (string) -- Transformation type (e.g. `derived_from`, `trained_on`, `preprocessed_from`, `merged_from`) - `metadata` (object) -- Optional edge metadata (e.g. transformation parameters) # List Dataset Attestations Source: https://docs.truthlocks.com/api-reference/machine-identity/datasets/list mint-openapi.yaml GET /v1/datasets Retrieve a paginated list of dataset attestations with optional filters. Returns a paginated list of dataset attestations within the tenant scope. Use query parameters to filter by agent, dataset name, or apply pagination controls. ### Response **datasets** `array` Array of dataset attestation objects. Each object contains `id`, `agent_id`, `name`, `version`, `hash`, `record_count`, `schema_version`, `source_uri`, `status`, `receipt_id`, `metadata`, and `created_at`. **total** `integer` Total number of dataset attestations matching the filter criteria. # Accept Cross-Tenant Delegation Source: https://docs.truthlocks.com/api-reference/machine-identity/delegations/accept mint-openapi.yaml POST /v1/delegations/cross-tenant/accept Accept a cross-tenant trust delegation offer, activating scoped permissions for the accepting agent. Accepts a pending cross-tenant trust delegation offer. Once accepted, the accepting agent gains the delegated scopes for the duration specified in the original offer. The acceptance event is recorded in the transparency log with a cryptographic receipt. Only agents within the target tenant specified in the original offer can accept it. The offer must still be in `offered` status and not yet expired. ### Response **id** `string` Delegation identifier. **status** `string` Updated status. `active` upon successful acceptance. **offered\_by\_agent\_id** `string` The agent that created the original offer. **offered\_by\_tenant\_id** `string` Tenant of the offering agent. **accepted\_by\_agent\_id** `string` The agent that accepted the delegation. **accepted\_by\_tenant\_id** `string` Tenant of the accepting agent. **scopes** `string[]` Delegated permission scopes now active for the accepting agent. **max\_depth** `integer` Maximum re-delegation depth. **accepted\_at** `string` ISO 8601 timestamp when the delegation was accepted. **expires\_at** `string` ISO 8601 timestamp when the delegation will automatically expire. **receipt\_id** `string` Transparency-log receipt anchoring this delegation acceptance event. # Offer Cross-Tenant Delegation Source: https://docs.truthlocks.com/api-reference/machine-identity/delegations/offer mint-openapi.yaml POST /v1/delegations/cross-tenant/offer Offer a scoped trust delegation to an agent in another tenant. Creates a cross-tenant trust delegation offer. Trust delegations allow agents in one tenant to grant specific, scoped permissions to agents in another tenant -- enabling secure multi-organization AI workflows without sharing credentials. Delegation offers are time-limited and scope-restricted. The target tenant must explicitly accept the offer before the delegation becomes active. All delegation lifecycle events are recorded in the transparency log. ### Delegation Constraints | Constraint | Limit | Description | | :- | :- | :- | | Max depth | 3 | Delegations cannot be re-delegated beyond 3 hops | | Max TTL | 24 hours | Delegations automatically expire after the specified duration | | Scope bound | Per-offer | Each delegation is limited to explicitly listed scopes | > [!WARNING] > > Cross-tenant delegations are a privileged operation. The offering agent must > have the `delegations:offer` permission and the target tenant must be in the > offering tenant's trusted partners list. ### Response **id** `string` Unique delegation offer identifier. **status** `string` Delegation status. Always `offered` on creation. **offered\_by\_agent\_id** `string` The agent that created the offer. **offered\_by\_tenant\_id** `string` Tenant of the offering agent. **target\_tenant\_id** `string` Target tenant that may accept the offer. **scopes** `string[]` Delegated permission scopes. **max\_depth** `integer` Maximum re-delegation depth. **expires\_at** `string` ISO 8601 timestamp when the offer expires if not accepted. **created\_at** `string` ISO 8601 timestamp of creation. # Get Document Verification Source: https://docs.truthlocks.com/api-reference/machine-identity/documents/get mint-openapi.yaml GET /v1/truth/document/{documentId} Retrieve the verification status and result for a submitted document Returns the current status and verification results for a previously submitted document. When processing is complete, the response includes both the AI verdict and (if applicable) the human verdict, along with the associated truth claim and receipt identifiers. ### Authentication Requires `X-API-Key` header or Bearer JWT token. The workspace is derived from the authenticated credential; do not send `X-Tenant-ID`. ### Response **document\_id** `string` The document verification record identifier. **agent\_id** `string` The agent that submitted the document. **document\_type** `string` The classification of the document. **file\_name** `string` The original file name. **document\_hash** `string` The SHA-256 hex digest of the document content. **status** `string` Current processing status. One of: - `processing` -- document is being analyzed - `verified` -- document passed verification - `disputed` -- document has conflicting signals - `rejected` -- document failed verification (tampering, forgery, or invalidity detected) **ai\_verdict** `string` The AI model's determination. One of: `authentic`, `suspicious`, `forged`, `inconclusive`. `null` while still processing. **ai\_confidence** `number` The AI model's confidence in its verdict as a float between `0.0` and `1.0`. `null` while still processing. **human\_verdict** `string` The human reviewer's determination, if human review was triggered. One of: `authentic`, `suspicious`, `forged`, `inconclusive`. `null` if not yet reviewed or human review was not required. **truth\_claim\_id** `string` The identifier of the truth claim automatically created for this document verification. Format: `maip-tc:ULID`. **receipt\_ids** `string[]` List of receipt identifiers minted during the verification process. Typically includes the verification receipt and, if applicable, the human review receipt. **created\_at** `string` ISO 8601 timestamp of when the document was submitted. **updated\_at** `string` ISO 8601 timestamp of the last status change. # Document Hash Record (Experimental) Source: https://docs.truthlocks.com/api-reference/machine-identity/documents/verify mint-openapi.yaml POST /v1/truth/document/verify Current document pipeline inputs and implementation limitations. > [!WARNING] > > The current implementation simulates extraction and AI verification. Its generated verdict and confidence are not evidence of document authenticity. Do not use this endpoint to approve identities, establish compliance, or authenticate documents. The handler accepts `agent_id` and `document_hash`, with optional `document_type`, `file_name`, and `metadata`. The agent must exist and be active. It does **not** accept document bytes in `document_b64`, perform OCR, or compare an uploaded file with the supplied hash. The handler creates its record synchronously. Use the returned document identifier with [Get Document](/api-reference/machine-identity/documents/get). Generated extraction hashes describe simulated content, not extracted file bytes. Pipeline receipt signatures currently contain system markers rather than cryptographic signatures. For cryptographic record verification, use [Verify Attestation](/api-reference/verify) with a real signed attestation and the original payload or document hash. That checks integrity and record status, not whether the document's factual claims are true. # Record a Guardrail Score Source: https://docs.truthlocks.com/api-reference/machine-identity/guardrails/check mint-openapi.yaml POST /v1/guardrails/check Apply thresholds to a score supplied by your application. Records your application's score for an agent's input or output. It does not scan raw text or calculate an independent safety score. Supply the score produced by your own detector. The required fields are `agent_id`, `check_type`, and `guardrail_type`. `check_type` must be `input` or `output`. | Submitted score | Result | | - | - | | Greater than 0.8 | `fail` | | Greater than 0.5, up to 0.8 | `warn` | | 0.5 or lower | `pass` | The current handler treats an omitted score as zero. Always send an explicit score; a `pass` result does not establish that content is safe. A failed check attempts to open the agent's circuit breaker. `content_hash` is metadata, not uploaded content for analysis. The current receipt uses a system marker in its signature field; do not treat it as cryptographic proof. # Kill Switch Source: https://docs.truthlocks.com/api-reference/machine-identity/killswitch/kill mint-openapi.yaml POST /v1/agents/{agentId}/kill Revoke an agent and delegated descendants, terminate sessions, and record the emergency decision. Use this endpoint for an emergency such as a compromised agent. Supply the agent identifier and a nonempty incident `reason` (maximum 2000 UTF-8 bytes). The authenticated workspace and environment determine which agent you can revoke. The operation revokes the agent and its delegated descendants, terminates their active sessions, revokes their active delegation links, and persists the decision in one database transaction. If that transaction fails, its state changes are rolled back. > [!WARNING] > > Revocation is permanent. Register a new agent if work needs to resume. Previously issued receipt evidence is preserved; this endpoint does not erase or rewrite it. ### Check the result A successful response has `status: "killed"`. `agents_changed` includes the requested agent; `cascade_count` counts newly revoked descendants. `sessions_terminated` and `delegations_revoked` report the affected sessions and delegation links. When managed signing succeeds, `receipt_status` is `signed` and `receipt_id` identifies a signed revocation receipt. Retrieve it through the receipts API. Signature validity and the revoked agent's lifecycle status are separate checks. When signing is unavailable, revocation still succeeds: `receipt_status` is `unavailable` and `receipt_id` is `null`. The durable revocation decision remains recorded. No signed receipt or automatic signing retry is implied by that response. ### Audit behavior The service records an `agent.killed` event and a revocation event alongside the state changes. A response does not establish external transparency anchoring, webhook delivery, or SIEM delivery. Verify those channels separately if your incident process depends on them. An unknown agent in the selected workspace environment returns `404`. An already revoked agent returns `409`. Review the existing state before retrying an emergency request. # Attest Model Source: https://docs.truthlocks.com/api-reference/machine-identity/models/attest mint-openapi.yaml POST /v1/models/attest Create a provenance attestation for an AI model, linking it to training datasets and recording framework metadata. Creates a cryptographically anchored attestation for an AI model. The attestation captures the model's framework, training lineage, hyperparameters, and evaluation metrics. It is linked to the originating agent and anchored in the transparency log. Model attestations provide an auditable record of what was trained, how it was trained, and what data was used -- enabling compliance teams and downstream consumers to verify model provenance before deployment. ### Response **id** `string` Unique model attestation identifier in MAIP format (`maip-model:ULID`). **agent\_id** `string` The agent that attested this model. **name** `string` Model name as provided in the request. **version** `string` Resolved version of the model. **framework** `string` ML framework identifier. **hash** `string` SHA-256 hex digest stored for integrity verification. **training\_dataset\_ids** `string[]` Linked training dataset attestation identifiers. **status** `string` Attestation status. Always `attested` on creation. **receipt\_id** `string` Transparency-log receipt anchoring this attestation. **created\_at** `string` ISO 8601 timestamp of creation. # Get Model Lineage Source: https://docs.truthlocks.com/api-reference/machine-identity/models/lineage mint-openapi.yaml GET /v1/models/{modelId}/lineage Retrieve the full lineage graph for a model, including training datasets and parent models. Returns the complete lineage graph for a model attestation. The graph includes all training datasets, parent models (for fine-tuned or distilled models), and downstream deployments connected by typed relationships. Model lineage enables compliance teams to trace exactly which data was used to train a model, verify that all upstream datasets are properly attested, and audit the full provenance chain from raw data to production deployment. ### Response **model\_id** `string` The root model identifier for this lineage query. **nodes** `array` Array of lineage nodes. Each node contains: - `id` (string) -- Resource identifier - `type` (string) -- Node type: `dataset`, `model`, or `deployment` * `name` (string) -- Human-readable name - `version` (string) -- Resource version - `status` (string) -- Current attestation status - `created_at` (string) -- ISO 8601 timestamp **edges** `array` Array of relationships connecting nodes. Each edge contains: - `source` (string) -- Source node identifier - `target` (string) -- Target node identifier - `relationship` (string) -- Relationship type (e.g. `trained_on`, `fine_tuned_from`, `distilled_from`, `deployed_as`) - `metadata` (object) -- Optional edge metadata **training\_datasets** `array` Convenience field listing all dataset nodes in the lineage that have a direct `trained_on` relationship with the queried model. Each entry contains `id`, `name`, `version`, and `status`. # Emit Event Source: https://docs.truthlocks.com/api-reference/machine-identity/observability/events mint-openapi.yaml POST /v1/events Emit a service observability event for auditing, alerting, and operational monitoring. Emits a structured observability event into the MAIP event stream. Events provide a unified audit trail of all significant actions across the machine-identity service -- from agent registration and session lifecycle to trust computation and orchestration completion. Events are persisted with tenant isolation, indexed for fast querying, and available for webhook delivery, SIEM integration, and the metrics aggregation pipeline. ### Event Types The `event_type` field uses a dot-separated namespace. The following event types are supported: | Category | Event Types | | :- | :- | | **Agent** | `agent.registered`, `agent.updated`, `agent.suspended`, `agent.revoked`, `agent.restored` | | **Session** | `session.created`, `session.refreshed`, `session.expired`, `session.revoked` | | **Trust** | `trust.computed`, `trust.threshold_breach`, `trust.delegation_offered`, `trust.delegation_accepted`, `trust.delegation_expired` | | **Orchestration** | `orchestration.started`, `orchestration.completed`, `orchestration.failed`, `orchestration.timeout` | | **Dataset** | `dataset.attested`, `dataset.lineage_updated` | | **Model** | `model.attested`, `model.lineage_updated` | | **Guardrail** | `guardrail.violation`, `guardrail.circuit_breaker_opened`, `guardrail.circuit_breaker_closed` | | **Anomaly** | `anomaly.reported`, `anomaly.resolved` | | **Kill Switch** | `killswitch.activated` | ### Response **id** `string` Unique event identifier in MAIP format (`maip-evt:ULID`). **event\_type** `string` The event type emitted. **agent\_id** `string` Associated agent identifier. **resource\_id** `string` Associated resource identifier. **severity** `string` Event severity level. **created\_at** `string` ISO 8601 timestamp of event creation. # Read MAIP service metadata Source: https://docs.truthlocks.com/api-reference/machine-identity/observability/metrics mint-openapi.yaml GET /v1/metrics Returns time-series metrics for agent activity. Supports multiple metric names and configurable time intervals for aggregation. Returns `service`, `supported_events`, `event_types`, and `generated_at` for the machine identity service. It is not a time-series metrics query. The handler does not consume granularity, period, or grouping parameters. # Create an Orchestration Execution Record Source: https://docs.truthlocks.com/api-reference/machine-identity/orchestrations/execute mint-openapi.yaml POST /v1/orchestrate/execute Creates a tracking record for a multi-agent orchestration. Creates a tracking record for a multi-agent orchestration. Supply `pattern`, `orchestrator_id`, and `agent_ids`, with optional `input_payload` and `metadata`. The current handler records an execution and returns HTTP 201. It does not itself execute your agents or guarantee that work has completed. An execution record or initial status is not evidence of completed tool calls. New automatically generated receipts use the managed signer. Verify each receipt; signing the tracking statement does not establish that the agents executed. Preserved historical placeholder signatures may remain unverifiable. Use the generated parameter fields above for the request contract. Authenticate with a credential for the target workspace and environment; do not supply a tenant-selection header. # Get Orchestration Source: https://docs.truthlocks.com/api-reference/machine-identity/orchestrations/get mint-openapi.yaml GET /v1/orchestrate/executions/{orchestrationId} Retrieve the full execution result of an orchestration, including step-level details and cost tracking. Returns the complete execution state of an orchestration, including its current status, every step executed, the final output, accumulated cost, and the transparency-log receipt once completed. Poll this endpoint to track orchestration progress. For real-time updates, configure a webhook for `orchestration.completed` and `orchestration.failed` events. ### Response **id** `string` Orchestration identifier. **agent\_id** `string` The agent that executed the orchestration. **workflow\_id** `string` The workflow definition identifier, if applicable. **status** `string` Current status: `running`, `completed`, `failed`, or `timeout`. **steps** `array` Ordered array of execution steps. Each step contains: - `step_number` (integer) -- Sequential step index (1-based) - `action` (string) -- Action performed (e.g. `llm_inference`, `tool_call`, `decision`, `guardrail_check`) - `result` (string) -- Step outcome summary - `duration_ms` (integer) -- Step execution time in milliseconds **output** `object` Final orchestration output. Present only when status is `completed`. **total\_cost\_cents** `number` Total accumulated cost of all LLM inferences and tool calls in US cents. **receipt\_id** `string` Transparency-log receipt anchoring the completed orchestration. Present only when status is `completed`. **started\_at** `string` ISO 8601 timestamp when execution began. **completed\_at** `string` ISO 8601 timestamp when execution finished. Present only for terminal states. **error** `object` Error details if status is `failed`. Contains `code` and `message`. # Record LLM Inference Source: https://docs.truthlocks.com/api-reference/machine-identity/orchestrations/llm-inference mint-openapi.yaml POST /v1/orchestrate/llm/inference Record an LLM inference call within an orchestration for cost tracking and provenance auditing. Records an individual LLM inference call that occurred within a running orchestration. Each inference record captures the model, provider, token counts, latency, cost, and content hashes -- enabling fine-grained cost attribution and provenance auditing of every AI decision. This endpoint is called by agent runtimes after each LLM API call completes. The inference record is linked to the parent orchestration and included in the final transparency-log receipt. ### Response **inference\_id** `string` Unique identifier for this inference record. **orchestration\_id** `string` Parent orchestration identifier. **model** `string` LLM model used. **provider** `string` LLM provider. **prompt\_tokens** `integer` Input token count. **completion\_tokens** `integer` Output token count. **cost\_cents** `number` Inference cost in US cents. **recorded\_at** `string` ISO 8601 timestamp when the inference was recorded. # Create MAIP Policy Source: https://docs.truthlocks.com/api-reference/machine-identity/policies/create mint-openapi.yaml POST /v1/maip/policies Create a new agent enforcement policy with conditional rules for runtime access control # Create MAIP Policy `POST /v1/maip/policies` Creates a new MAIP agent enforcement policy for the authenticated tenant. Policies define runtime rules that are evaluated when agents request access to scoped resources via the [Evaluate Policy](/api-reference/machine-identity/policies/evaluate) endpoint. > [!NOTE] > > MAIP policies are different from [RBAC issuance > policies](/api-reference/policies/create). MAIP policies govern **machine > agent** behavior at runtime based on trust scores, delegation depth, scopes, > and agent type. RBAC policies govern credential issuance and human user > access. ### Authentication Requires `X-API-Key` header or Bearer JWT token. Tenant-scoped via cookie or JWT claim. ### Response Returns the created policy object with server-generated fields (`id`, `tenant_id`, `status`, timestamps). **id** `string` UUID primary key of the created policy. **tenant\_id** `string` UUID of the owning tenant. **name** `string` Policy name as provided. **description** `string` Policy description, if provided. **category** `string` Policy category. **status** `string` Always `"active"` on creation. **priority** `integer` Evaluation priority. **rules** `object` The rules array as provided. **created\_at** `string` ISO 8601 creation timestamp. **updated\_at** `string` ISO 8601 last-updated timestamp. ### Example ```bash theme={null} curl -X POST https://api.truthlocks.com/v1/maip/policies \ -H "X-API-Key: tl_live_..." \ -H "Content-Type: application/json" \ -d '{ "name": "Block Low-Trust Write Operations", "description": "Deny data:write scope access for agents with trust score below 0.5", "category": "trust", "priority": 10, "rules": [ { "conditions": [ {"field": "trust_score", "op": "lt", "value": 0.5}, {"field": "scope", "op": "eq", "value": "data:write"} ], "effect": "deny", "requires_approval": false } ] }' ``` ```javascript theme={null} const response = await fetch("https://api.truthlocks.com/v1/maip/policies", { method: "POST", headers: { "X-API-Key": "tl_live_...", "Content-Type": "application/json", }, body: JSON.stringify({ name: "Block Low-Trust Write Operations", description: "Deny data:write scope access for agents with trust score below 0.5", category: "trust", priority: 10, rules: [ { conditions: [ { field: "trust_score", op: "lt", value: 0.5 }, { field: "scope", op: "eq", value: "data:write" }, ], effect: "deny", requires_approval: false, }, ], }), }); const policy = await response.json(); ``` ```python theme={null} import requests response = requests.post( "https://api.truthlocks.com/v1/maip/policies", headers={ "X-API-Key": "tl_live_...", "Content-Type": "application/json", }, json={ "name": "Block Low-Trust Write Operations", "description": "Deny data:write scope access for agents with trust score below 0.5", "category": "trust", "priority": 10, "rules": [ { "conditions": [ {"field": "trust_score", "op": "lt", "value": 0.5}, {"field": "scope", "op": "eq", "value": "data:write"}, ], "effect": "deny", "requires_approval": False, } ], }, ) policy = response.json() ``` # Evaluate MAIP Policy Source: https://docs.truthlocks.com/api-reference/machine-identity/policies/evaluate mint-openapi.yaml POST /v1/maip/policies/evaluate Evaluate all active agent policies against a specific agent and requested scope # Evaluate MAIP Policy `POST /v1/maip/policies/evaluate` Evaluates all active MAIP policies for the authenticated tenant against a specific agent and requested scope. Returns whether the action is allowed, denied, or requires human approval. This is the runtime enforcement checkpoint that agents call before performing sensitive operations. > [!NOTE] > > Policy evaluation uses a **deny-overrides** model: if any active policy with a > matching `deny` rule triggers, the action is blocked regardless of any `allow` > rules. The `requires_approval` flag is additive -- it can be set even when the > action is allowed. ### Authentication Requires `X-API-Key` header or Bearer JWT token. Tenant-scoped via cookie or JWT claim. ### Evaluation Logic The evaluation performs three sequential checks: 1. **Agent Status Check** -- The agent must have `status: "active"`. Suspended or revoked agents are always denied. 2. **Scope Access Check** -- The requested scope must be present in the agent's granted scopes. Explicitly denied scopes (prefixed with `!`) always block access. 3. **Policy Rules Check** -- All active tenant policies are evaluated in priority order. Each rule's conditions are AND-ed. If any `deny` rule matches, the action is blocked. ### Response **allowed** `boolean` `true` if the action is permitted, `false` if denied by any check. **denied\_by** `string[]` Names of the policies that denied the action. Empty array if allowed. **reason** `string` Human-readable reason for denial. One of: - `"agent is not active"` -- Agent is suspended or revoked - `"scope not granted to agent"` -- Scope not in agent's granted scopes - `"denied by policy"` -- One or more policies blocked the action **requires\_approval** `boolean` `true` if any matching policy rule has `requires_approval: true`, even if the action is otherwise allowed. The caller should present a human approval workflow before proceeding. ### Example ```bash theme={null} curl -X POST https://api.truthlocks.com/v1/maip/policies/evaluate \ -H "X-API-Key: tl_live_..." \ -H "Content-Type: application/json" \ -d '{ "agent_id": "maip:t1234567:01HYX3KPZQ7RJGBN0WFMV8SDEH", "scope": "data:write", "action": "update_customer_record", "resource": "customers/cust_12345" }' ``` ```javascript theme={null} const response = await fetch( "https://api.truthlocks.com/v1/maip/policies/evaluate", { method: "POST", headers: { "X-API-Key": "tl_live_...", "Content-Type": "application/json", }, body: JSON.stringify({ agent_id: "maip:t1234567:01HYX3KPZQ7RJGBN0WFMV8SDEH", scope: "data:write", action: "update_customer_record", resource: "customers/cust_12345", }), }, ); const result = await response.json(); if (!result.allowed) { console.error(`Denied by: ${result.denied_by.join(", ")}`); } else if (result.requires_approval) { // Route to human approval workflow } ``` ```python theme={null} import requests response = requests.post( "https://api.truthlocks.com/v1/maip/policies/evaluate", headers={ "X-API-Key": "tl_live_...", "Content-Type": "application/json", }, json={ "agent_id": "maip:t1234567:01HYX3KPZQ7RJGBN0WFMV8SDEH", "scope": "data:write", "action": "update_customer_record", "resource": "customers/cust_12345", }, ) result = response.json() ``` # List MAIP Policies Source: https://docs.truthlocks.com/api-reference/machine-identity/policies/list mint-openapi.yaml GET /v1/maip/policies List all agent enforcement policies for the authenticated tenant # List MAIP Policies `GET /v1/maip/policies` Returns all MAIP agent policies configured for the authenticated tenant. Policies define runtime enforcement rules that govern what agents can do based on trust scores, scopes, delegation depth, and agent type. ### Authentication Requires `X-API-Key` header or Bearer JWT token. Tenant-scoped via cookie or JWT claim. ### Response Returns an array of policy objects. **id** `string` UUID primary key of the policy. **tenant\_id** `string` UUID of the owning tenant. **name** `string` Human-readable policy name. Used in denial messages and audit logs. **description** `string` Detailed description of what the policy enforces. **category** `string` Policy category. One of: `"scope"`, `"trust"`, `"rate"`, `"custom"`. **status** `string` Policy lifecycle status. One of: `"active"`, `"disabled"`, `"archived"`. Only `active` policies are evaluated during policy checks. **priority** `integer` Evaluation priority. Lower numbers are evaluated first. Default: `100`. **rules** `object` JSON array of policy rules. Each rule contains conditions, an effect (`"allow"`, `"deny"`, `"require_approval"`), and an optional `requires_approval` flag. See [Create Policy](#create-policy) for the full rule schema. **created\_at** `string` ISO 8601 creation timestamp. **updated\_at** `string` ISO 8601 last-updated timestamp. ### Example ```bash theme={null} curl https://api.truthlocks.com/v1/maip/policies \ -H "X-API-Key: tl_live_..." ``` ```javascript theme={null} const response = await fetch("https://api.truthlocks.com/v1/maip/policies", { headers: { "X-API-Key": "tl_live_..." }, }); const policies = await response.json(); ``` ```python theme={null} import requests response = requests.get( "https://api.truthlocks.com/v1/maip/policies", headers={"X-API-Key": "tl_live_..."}, ) policies = response.json() ``` # Create Scope Source: https://docs.truthlocks.com/api-reference/machine-identity/scopes/create mint-openapi.yaml POST /v1/scopes Create a custom tenant-scoped permission scope for fine-grained agent access control # Create Scope `POST /v1/scopes` Creates a custom permission scope for the authenticated tenant. Custom scopes extend the built-in scope registry with tenant-specific permissions. The scope string is automatically composed from the `resource` and `action` fields in `resource:action` format. Custom scopes are validated against the MAIP scope format rules: alphanumeric characters, dots, underscores, hyphens, and asterisks only. > [!NOTE] > > Custom scopes are tenant-isolated. They do not appear in other tenants' scope > registries. Built-in platform scopes cannot be overridden or duplicated. ### Authentication Requires `X-API-Key` header or Bearer JWT token. The workspace is derived from the authenticated credential; do not send `X-Tenant-ID`. ### Response **id** `string` UUID of the newly created scope definition. **tenant\_id** `string` UUID of the owning tenant. **scope** `string` The composed scope string in `resource:action` format. **resource** `string` The resource component. **action** `string` The action component. **display\_name** `string` Human-readable scope name. **description** `string` Scope description. **category** `string` Scope category. **is\_builtin** `boolean` Always `false` for tenant-created scopes. **created\_at** `string` ISO 8601 creation timestamp. ### Example ```bash theme={null} curl -X POST https://api.truthlocks.com/v1/scopes \ -H "X-API-Key: tl_live_..." \ -H "Content-Type: application/json" \ -d '{ "resource": "crm", "action": "contact.enrich", "display_name": "CRM Contact Enrichment", "description": "Allows agents to enrich CRM contact records via third-party providers", "category": "integration" }' ``` *** ### Assigning Custom Scopes to Agents After creating a custom scope, assign it to agents during [registration](/api-reference/machine-identity/agents/register) or via [delegation](/api-reference/machine-identity/agents/register): ```bash theme={null} curl -X POST https://api.truthlocks.com/v1/agents \ -H "X-API-Key: tl_live_..." \ -H "Content-Type: application/json" \ -d '{ "agent_type": "pipeline", "display_name": "CRM Enrichment Pipeline", "scopes": ["crm:contact.enrich", "data:read"] }' ``` # List Scopes Source: https://docs.truthlocks.com/api-reference/machine-identity/scopes/list mint-openapi.yaml GET /v1/scopes List all available permission scopes including platform built-ins and tenant custom scopes # List Scopes `GET /v1/scopes` Returns all permission scopes available to the authenticated tenant. This includes platform-defined built-in scopes and any custom scopes created by the tenant. Scopes follow the `resource:action` format defined by the MAIP protocol. ### Authentication Requires `X-API-Key` header or Bearer JWT token. The workspace is derived from the authenticated credential; do not send `X-Tenant-ID`. ### Response Returns an array of scope definition objects. **id** `string` UUID of the scope definition. **tenant\_id** `string` UUID of the tenant that owns this scope. `null` for platform-level built-in scopes. **scope** `string` The full scope string in `resource:action` format (e.g., `"data:read"`, `"model:train"`). **resource** `string` The resource component of the scope (e.g., `"data"`, `"model"`, `"tool"`). **action** `string` The action component of the scope (e.g., `"read"`, `"write"`, `"*"`). **display\_name** `string` Human-readable name for the scope. **description** `string` Detailed description of what the scope grants access to. **category** `string` Scope category for organizational purposes. **is\_builtin** `boolean` `true` for platform-defined scopes, `false` for tenant-created custom scopes. **created\_at** `string` ISO 8601 creation timestamp. ### Example ```bash theme={null} curl -G https://api.truthlocks.com/v1/scopes \ -H "X-API-Key: tl_live_..." \ -d "category=data" ``` *** ### Built-in Scope Categories The platform provides 25+ built-in scopes across 6 categories: | Category | Scopes | Description | | - | - | - | | `data` | `read`, `write`, `delete`, `*` | Data resource access | | `model` | `train`, `evaluate`, `deploy`, `attest`, `*` | ML model lifecycle | | `tool` | `search.web`, `search.db`, `execute`, `*` | Tool invocation | | `agent` | `delegate`, `manage`, `inspect`, `*` | Agent lifecycle management | | `admin` | `config`, `audit`, `billing`, `*` | Administrative operations | | `receipt` | `create`, `verify`, `revoke`, `*` | Receipt management | ### Scope Format Reference ``` resource:action Standard scope (e.g., "data:read") resource:* Wildcard scope (e.g., "data:*" grants all data actions) !resource:action Negation scope (e.g., "!data:delete" explicitly denies) resource:sub.action Dotted sub-actions (e.g., "tool:search.web") ``` # Create Session Source: https://docs.truthlocks.com/api-reference/machine-identity/sessions/create mint-openapi.yaml POST /v1/agent-sessions Create a time-bound authenticated session for a machine agent with scoped access tokens # Create Session `POST /v1/agent-sessions` Creates a new authenticated session for a machine agent. The session binds a time-limited access token and refresh token to the agent, with an explicit scope set that must be a subset of the agent's granted scopes. The `token` and `refresh_token` are returned only in the creation response. Store them securely -- they cannot be retrieved later. > [!WARNING] > > The `token` and `refresh_token` fields are only returned once in this > response. Store them in a secure secrets manager or encrypted storage > immediately. If lost, terminate the session and create a new one. ### Authentication Requires `X-API-Key` header or Bearer JWT token. The workspace is derived from the authenticated credential; do not send `X-Tenant-ID`. ### Response **session** `object` The created session object containing: **session.id** `string` Internal UUID primary key. **session.session\_id** `string` MAIP session identifier in format `maip-sess::`. Use this ID in subsequent API calls. **session.agent\_id** `string` The agent this session belongs to. **session.status** `string` Session status. Always `"active"` on creation. **session.scopes** `string[]` The effective scopes for this session. **session.metadata** `object` Session metadata. **session.expires\_at** `string` ISO 8601 expiration timestamp. **session.created\_at** `string` ISO 8601 creation timestamp. **session.updated\_at** `string` ISO 8601 last-updated timestamp. **token** `string` Opaque access token for authenticating API requests within this session. 64-character hex string. **Returned only once.** **refresh\_token** `string` Token for refreshing the session before expiry. 64-character hex string. **Returned only once.** ### Example ```bash theme={null} curl -X POST https://api.truthlocks.com/v1/agent-sessions \ -H "X-API-Key: tl_live_..." \ -H "Content-Type: application/json" \ -d '{ "agent_id": "maip:t1234567:01HYX3KPZQ7RJGBN0WFMV8SDEH", "scopes": ["data:read", "tool:search.web"], "ttl_minutes": 120, "metadata": { "purpose": "customer-inquiry-batch-2026-04-06", "orchestrator": "support-pipeline-v2" } }' ``` *** ### Session Lifecycle ``` Created (active) --> Refreshed (active) --> Expired (expired) | | +--> Terminated (terminated) | | | +--> Handed Off (handed_off) --> New Session (active) ``` A session receipt is automatically created when the session starts, linking the session to the agent's audit trail. # List Sessions Source: https://docs.truthlocks.com/api-reference/machine-identity/sessions/list mint-openapi.yaml GET /v1/agent-sessions List agent sessions with filtering by agent, status, and pagination # List Sessions `GET /v1/agent-sessions` Returns a paginated list of agent sessions for the authenticated tenant. Results can be filtered by agent ID and session status. Sessions are returned in reverse chronological order (newest first). ### Authentication Requires `X-API-Key` header or Bearer JWT token. The workspace is derived from the authenticated credential; do not send `X-Tenant-ID`. ### Response **sessions** `object[]` Array of session objects. Each contains `session_id`, `agent_id`, `status`, `scopes`, `metadata`, `expires_at`, `parent_session_id`, `handed_off_to`, `ip_address`, `user_agent`, `refreshed_at`, `terminated_at`, `created_at`, and `updated_at`. Token hashes are never exposed in list responses. **total** `integer` Total count of sessions matching the filter criteria, across all pages. ### Example ```bash theme={null} curl -G https://api.truthlocks.com/v1/agent-sessions \ -H "X-API-Key: tl_live_..." \ -d "agent_id=maip:t1234567:01HYX3KPZQ7RJGBN0WFMV8SDEH" \ -d "status=active" \ -d "limit=25" \ -d "offset=0" ``` *** ### Session Status Reference | Status | Description | | - | - | | `active` | Session is valid and accepting requests | | `expired` | Session TTL has elapsed; no longer valid | | `terminated` | Session was explicitly terminated via API | | `handed_off` | Session was transferred to another agent via handoff | # Terminate Session Source: https://docs.truthlocks.com/api-reference/machine-identity/sessions/terminate mint-openapi.yaml DELETE /v1/agent-sessions/{sessionId} Immediately terminate an active agent session, invalidating its tokens # Terminate Session `DELETE /v1/agent-sessions/{sessionID}` Immediately terminates an active agent session. The session's access token and refresh token are invalidated, and the session status transitions to `"terminated"`. Any subsequent API calls using this session's tokens will be rejected. > [!NOTE] > > Session termination is recorded in the audit log with a > `AGENT_SESSION_TERMINATED` event. A termination receipt is not automatically > generated -- use the receipts API to create one if your compliance workflow > requires it. ### Authentication Requires `X-API-Key` header or Bearer JWT token. The workspace is derived from the authenticated credential; do not send `X-Tenant-ID`. ### Response **status** `string` Updated status, always `"terminated"` on success. **session\_id** `string` The MAIP session identifier that was terminated. ### Example ```bash theme={null} curl -X DELETE https://api.truthlocks.com/v1/agent-sessions/maip-sess:a1b2c3d4:9f8e7d6c5b4a3210 \ -H "X-API-Key: tl_live_..." \ -H "Content-Type: application/json" \ -d '{ "reason": "Task completed. Cleaning up session resources." }' ``` *** ### Bulk Session Cleanup To terminate all active sessions for a specific agent (e.g., during incident response), list sessions filtered by agent and status, then terminate each: ```bash theme={null} # 1. List active sessions for the agent SESSIONS=$(curl -s -G https://api.truthlocks.com/v1/agent-sessions \ -H "X-API-Key: tl_live_..." \ -d "agent_id=maip:t1234567:01HYX3KPZQ7RJGBN0WFMV8SDEH" \ -d "status=active" \ | jq -r '.sessions[].session_id') # 2. Terminate each session for SID in $SESSIONS; do curl -X DELETE "https://api.truthlocks.com/v1/agent-sessions/$SID" \ -H "X-API-Key: tl_live_..." \ -H "Content-Type: application/json" \ -d '{"reason": "Bulk cleanup during incident response SI-2026-0412"}' done ``` > [!NOTE] > > For faster incident response, [suspending the > agent](/api-reference/machine-identity/agents/suspend) immediately blocks all > session operations without requiring individual session termination. # Invoke Tool Source: https://docs.truthlocks.com/api-reference/machine-identity/tools/invoke mint-openapi.yaml POST /v1/tools/{toolName}/invoke Request tool invocation with scope validation, rate limiting, and audit receipt generation # Invoke Tool `POST /v1/tools/{toolName}/invoke` Requests invocation of a registered tool on behalf of a machine agent. The platform performs a multi-layer access control check before granting access: 1. **Agent status** -- agent must be `"active"` 2. **Scope check** -- agent must hold the tool's required scope 3. **Rate limit** -- agent must not exceed the tool's per-minute rate limit 4. **Approval gate** -- if the tool requires approval, the response is `pending_approval`; the current handler does not create an approval request If all checks pass, the invocation is recorded. Current tool receipts use a system marker rather than a cryptographic signature. They are audit records, not independently verifiable signed proofs. > [!NOTE] > > This endpoint performs the **access control decision** and records the decision. It does not proxy the actual tool execution. Your application is > responsible for calling the tool's underlying endpoint after receiving an > `"allowed"` response. ### Authentication Requires `X-API-Key` header or Bearer JWT token. The workspace is derived from the authenticated credential; do not send `X-Tenant-ID`. ### Response **allowed** `boolean` Whether the invocation was authorized. `true` if all access control checks passed. **status** `string` Invocation status. One of: `"allowed"`, `"denied"`, `"pending_approval"`. **reason** `string` Human-readable explanation when the invocation is denied or pending. Not present when allowed. **receipt\_id** `string` Unique receipt identifier for the invocation, linking to the audit trail. Only present when `status` is `"allowed"`. **requires\_approval** `boolean` `true` when the tool requires human approval. The invocation is not automatically queued for approval. Only present when `status` is `"pending_approval"`. ### Example: Allowed Invocation ```bash theme={null} curl -X POST https://api.truthlocks.com/v1/tools/search.web/invoke \ -H "X-API-Key: tl_live_..." \ -H "Content-Type: application/json" \ -d '{ "agent_id": "maip:t1234567:01HYX3KPZQ7RJGBN0WFMV8SDEH", "session_id": "maip-sess:a1b2c3d4:9f8e7d6c5b4a3210" }' ``` *** ### Access Control Flow ``` POST /v1/tools/{name}/invoke | +-- Is agent active? | No --> { allowed: false, status: "denied", reason: "agent is not active" } | +-- Does agent have required scope? | No --> { allowed: false, status: "denied", reason: "agent lacks required scope: ..." } | +-- Is rate limit exceeded? | Yes --> { allowed: false, status: "denied", reason: "rate limit exceeded" } | +-- Does tool require approval? | Yes --> { allowed: false, status: "pending_approval", requires_approval: true } | +-- Create receipt + record invocation --> { allowed: true, status: "allowed", receipt_id: "..." } ``` ### Integration Pattern After receiving an `"allowed"` response, execute the tool and optionally record the outcome: ```bash theme={null} # 1. Request invocation authorization RESPONSE=$(curl -s -X POST https://api.truthlocks.com/v1/tools/search.web/invoke \ -H "X-API-Key: tl_live_..." \ -H "Content-Type: application/json" \ -d '{"agent_id": "maip:t1234567:01HYX3KPZQ7RJGBN0WFMV8SDEH"}') ALLOWED=$(echo "$RESPONSE" | jq -r '.allowed') RECEIPT_ID=$(echo "$RESPONSE" | jq -r '.receipt_id') # 2. Execute the tool only if explicitly authorized if [ "$ALLOWED" = "true" ]; then RESULT=$(curl -s "https://serpapi.com/search?q=example&api_key=...") echo "Tool executed. Receipt: $RECEIPT_ID" fi ``` # Register Tool Source: https://docs.truthlocks.com/api-reference/machine-identity/tools/register mint-openapi.yaml POST /v1/tools Register a tool in the MAIP tool registry with scope requirements, risk classification, and rate limits # Register Tool `POST /v1/tools` Registers a new tool in the tenant's MAIP tool registry. Tools represent external capabilities (APIs, functions, services) that machine agents can invoke. Each tool is associated with a required scope, risk level, and optional approval gate. The platform automatically elevates the risk level to `"high"` if the tool name or required scope contains dangerous action verbs (write, delete, send, execute, deploy, destroy, drop, truncate). > [!NOTE] > > Tool names must be unique per tenant. Attempting to register a tool with a > name that already exists returns `409 Conflict`. ### Authentication Requires `X-API-Key` header or Bearer JWT token. The workspace is derived from the authenticated credential; do not send `X-Tenant-ID`. ### Response **id** `string` UUID of the newly registered tool. **tenant\_id** `string` UUID of the owning tenant. **name** `string` Machine-readable tool name. **display\_name** `string` Human-readable tool name. **description** `string` Tool description. **scope\_required** `string` Required scope for invocation. **risk\_level** `string` Effective risk classification (may be auto-elevated). **requires\_approval** `boolean` Whether human approval is required. **rate\_limit\_per\_minute** `integer` Per-agent rate limit. **category** `string` Tool category. **status** `string` Tool status. Always `"active"` on creation. **metadata** `object` Tool metadata. **created\_at** `string` ISO 8601 creation timestamp. **updated\_at** `string` ISO 8601 last-updated timestamp. ### Example ```bash theme={null} curl -X POST https://api.truthlocks.com/v1/tools \ -H "X-API-Key: tl_live_..." \ -H "Content-Type: application/json" \ -d '{ "name": "search.web", "display_name": "Web Search", "description": "Performs web searches via SerpAPI and returns structured results", "scope_required": "tool:search.web", "risk_level": "low", "rate_limit_per_minute": 30, "category": "search", "metadata": { "endpoint_url": "https://serpapi.com/search", "auth_type": "api_key", "max_results": 10 } }' ``` *** ### Risk Level Auto-Elevation The platform scans tool names and scope requirements for dangerous action verbs. If detected, the risk level is automatically elevated: | Detected Verb | Auto-Elevation | | - | - | | `write`, `delete`, `send` | Elevated to `"high"` | | `execute`, `deploy`, `destroy` | Elevated to `"high"` | | `drop`, `truncate` | Elevated to `"high"` | Tools with `"critical"` risk level always require human approval regardless of the `requires_approval` setting. # Compute Trust Score Source: https://docs.truthlocks.com/api-reference/machine-identity/trust-scores/compute mint-openapi.yaml POST /v1/trust/compute Recompute the trust score for a machine agent based on current behavioral signals Triggers an on-demand recomputation of the trust score for a specific agent. The score is derived from multiple weighted factors including anomaly rate, uptime history, delegation depth, and receipt volume. Use this endpoint after a significant event (key rotation, policy violation, attestation burst) to ensure the score reflects the agent's current posture. Trust scores range from `0.0` (no trust) to `1.0` (full trust) and are used by policy engines, witness selection, and delegation gates across the platform. ### Authentication Requires `X-API-Key` header or Bearer JWT token. The workspace is derived from the authenticated credential; do not send `X-Tenant-ID`. ### Response **agent\_id** `string` The agent identifier that was scored. **score** `number` The computed trust score as a float between `0.0` and `1.0`. **factors** `object` Breakdown of the individual factors that contributed to the score. **Factor fields** **factors.anomaly\_rate** `number` Ratio of anomalous events to total events in the scoring window. Lower is better. **factors.uptime** `number` Agent availability ratio over the last 30 days. `1.0` means 100% uptime. **factors.delegation\_depth** `integer` Current depth of the agent's delegation chain. Deep chains reduce trust. **factors.receipt\_count** `integer` Total number of valid receipts the agent has accumulated. **computed\_at** `string` ISO 8601 timestamp of when the computation completed. ### Score Factor Weights | Factor | Weight | Description | | :- | :- | :- | | `anomaly_rate` | 30% | Penalizes agents with high anomaly ratios | | `uptime` | 25% | Rewards consistent availability | | `delegation_depth` | 20% | Deeper chains reduce trust proportionally | | `receipt_count` | 25% | More receipts indicate established history | # Get Trust Score Source: https://docs.truthlocks.com/api-reference/machine-identity/trust-scores/get mint-openapi.yaml GET /v1/agents/{agentId}/trust-score Retrieve the current trust score for a machine agent Returns the most recently computed trust score for a specific agent. This is a lightweight read that returns cached data -- it does not trigger a recomputation. If the score is stale, call the [Compute Trust Score](/api-reference/machine-identity/trust-scores/compute) endpoint to refresh it. Trust scores are used across the platform for witness eligibility, delegation authorization, and policy evaluation. ### Authentication Requires `X-API-Key` header or Bearer JWT token. The workspace is derived from the authenticated credential; do not send `X-Tenant-ID`. ### Response **agent\_id** `string` The agent identifier. **score** `number` The current trust score as a float between `0.0` and `1.0`. **factors** `object` Breakdown of the individual factors that contributed to the score. **Factor fields** **factors.anomaly\_rate** `number` Ratio of anomalous events to total events in the scoring window. **factors.uptime** `number` Agent availability ratio over the last 30 days. **factors.delegation\_depth** `integer` Current depth of the agent's delegation chain. **factors.receipt\_count** `integer` Total number of valid receipts the agent has accumulated. **updated\_at** `string` ISO 8601 timestamp of the last score computation. # Trust Score History Source: https://docs.truthlocks.com/api-reference/machine-identity/trust-scores/history mint-openapi.yaml GET /v1/agents/{agentId}/trust-history Retrieve historical trust score data for a machine agent over time Returns a time-series of trust score computations for a specific agent. Use this endpoint to visualize trust trends, detect score degradation, and audit score changes following incidents. Results are ordered chronologically (oldest first). ### Authentication Requires `X-API-Key` header or Bearer JWT token. The workspace is derived from the authenticated credential; do not send `X-Tenant-ID`. ### Response **agent\_id** `string` The agent identifier. **history** `array` Array of historical trust score records, ordered by `computed_at` ascending. **History record fields** **history\[].score** `number` Trust score at the time of computation (`0.0`-`1.0`). **history\[].factors** `object` Factor breakdown at the time of computation. **Factor fields** **history\[].factors.anomaly\_rate** `number` Anomaly rate at time of computation. **history\[].factors.uptime** `number` Uptime ratio at time of computation. **history\[].factors.delegation\_depth** `integer` Delegation chain depth at time of computation. **history\[].factors.receipt\_count** `integer` Cumulative receipt count at time of computation. **history\[].computed\_at** `string` ISO 8601 timestamp of when this score was computed. **total** `integer` Total number of records matching the query window (before limit is applied). # Create Truth Claim Source: https://docs.truthlocks.com/api-reference/machine-identity/truth-claims/create mint-openapi.yaml POST /v1/truth/claim Submit a new truth claim from a machine agent for verification Creates a new truth claim -- a formal assertion made by a machine agent about a subject. Truth claims are the foundational data objects in the MAIP verification pipeline. Once created, a claim can be routed through witness verification, AI analysis, or human review before receiving a final determination. Claims are immutable once created. The `status` field tracks the claim through its lifecycle from `pending` to a terminal state (`verified`, `disputed`, or `rejected`). A receipt is automatically minted when the claim reaches a terminal state. ### Authentication Requires `X-API-Key` header or Bearer JWT token. The workspace is derived from the authenticated credential; do not send `X-Tenant-ID`. ### Response **id** `string` Unique identifier for the truth claim. Format: `maip-tc:ULID`. **agent\_id** `string` The agent that created the claim. **claim\_type** `string` The classification of the claim. **subject** `string` The entity or resource the claim is about. **assertion** `string` The assertion being made. **status** `string` Initial status. Always `pending` on creation. **created\_at** `string` ISO 8601 timestamp of creation. ### Claim Lifecycle | Status | Description | | :- | :- | | `pending` | Created, awaiting verification | | `verifying` | Verification in progress (witness, AI, or human) | | `verified` | Claim confirmed as truthful | | `disputed` | Claim contested -- conflicting evidence found | | `rejected` | Claim determined to be false | # Get Truth Claim Source: https://docs.truthlocks.com/api-reference/machine-identity/truth-claims/status mint-openapi.yaml GET /v1/truth/claims/{claimId}/status Retrieve a truth claim with its current status and verification result Returns the full details of a truth claim including its current lifecycle status, the original assertion, and -- if verification is complete -- the verification result and associated receipt. Use this endpoint to check whether a claim has been verified, disputed, or rejected. ### Authentication Requires `X-API-Key` header or Bearer JWT token. The workspace is derived from the authenticated credential; do not send `X-Tenant-ID`. ### Response **id** `string` The truth claim identifier. **agent\_id** `string` The agent that created the claim. **claim\_type** `string` Classification of the claim (`identity`, `integrity`, `provenance`, `compliance`, `capability`). **subject** `string` The entity or resource the claim is about. **assertion** `string` The assertion being made. **status** `string` Current lifecycle status. One of: `pending`, `verifying`, `verified`, `disputed`, `rejected`. **confidence** `number` The original agent's self-reported confidence in the assertion. **evidence\_urls** `string[]` URLs pointing to supporting evidence submitted with the claim. **metadata** `object` Arbitrary key-value metadata attached to the claim. **verification\_result** `object` Present only when verification is complete. Contains the determination details. **Verification result fields** **verification\_result.method** `string` The verification method used (`witness`, `ai`, `human`). **verification\_result.determination** `string` The final determination: `verified`, `disputed`, or `rejected`. **verification\_result.confidence** `number` The verification system's confidence in the determination (`0.0`-`1.0`). **verification\_result.reasoning** `string` Human-readable explanation of the determination. **verification\_result.completed\_at** `string` ISO 8601 timestamp of when verification completed. **receipt\_id** `string` The receipt identifier minted when the claim reached a terminal state. `null` if still pending or verifying. **created\_at** `string` ISO 8601 timestamp of when the claim was created. **updated\_at** `string` ISO 8601 timestamp of the last status change. # Record a Verification Verdict Source: https://docs.truthlocks.com/api-reference/machine-identity/truth-claims/verify mint-openapi.yaml POST /v1/truth/verify Records a verdict supplied by a separate verifier agent. It does not run an independent fact-checking model. Records a verdict supplied by a separate verifier agent. It does not run an independent fact-checking model. Supply `claim_id`, `verifier_agent_id`, and `verdict` (`confirmed`, `disputed`, or `inconclusive`). The verifier must exist and differ from the claimant. Optional evidence references and methodology describe your verification process; they are not automatically validated. The service aggregates submitted verifications to update the claim score. Generated truth-verification receipts currently use system markers, not cryptographic signatures. Use the generated parameter fields above for the request contract. Authenticate with a credential for the target workspace and environment; do not supply a tenant-selection header. # Submit a Witness Attestation Source: https://docs.truthlocks.com/api-reference/machine-identity/witness/attest mint-openapi.yaml POST /v1/witness/{witnessRequestID}/attest Records an agent response to an existing witness request. Records an agent response to an existing witness request. The path `witnessRequestID` is the request UUID. Supply `witness_agent_id`, `trust_domain`, `signature`, and `attestation` (`agree`, `disagree`, or `abstain`). The request must be pending and unexpired; the witness must differ from the requester. The current handler stores the submitted signature but does not cryptographically verify it. Consensus aggregates submitted votes; it does not independently prove the claim is true. Use the generated parameter fields above for the request contract. Authenticate with a credential for the target workspace and environment; do not supply a tenant-selection header. # Get Witness Consensus Source: https://docs.truthlocks.com/api-reference/machine-identity/witness/consensus mint-openapi.yaml GET /v1/witness/{witnessRequestID}/consensus Retrieve the consensus result for a witness verification request Returns the current consensus state for a witness request, including vote tallies and final determination. Use this endpoint to poll for consensus completion or to retrieve the final result after witnesses have attested. Consensus is computed automatically when the number of attestations reaches the `required_witnesses` threshold. A simple majority of `confirm` or `deny` verdicts determines the outcome. `abstain` votes count toward the quorum but do not influence the majority calculation. ### Authentication Requires `X-API-Key` header or Bearer JWT token. The workspace is derived from the authenticated credential; do not send `X-Tenant-ID`. ### Response **id** `string` The witness request identifier. **claim\_id** `string` The truth claim that was being witnessed. **status** `string` Current status of the witness request. One of: - `pending` -- still awaiting attestations - `confirmed` -- consensus reached, claim is confirmed - `denied` \-- consensus reached, claim is denied - `expired` -- TTL elapsed without reaching quorum **required\_witnesses** `integer` Number of attestations required for consensus. **confirmations** `integer` Number of `confirm` verdicts received. **denials** `integer` Number of `deny` verdicts received. **abstentions** `integer` Number of `abstain` verdicts received. **consensus\_reached** `boolean` Whether the required quorum has been met and a determination made. **consensus\_at** `string` ISO 8601 timestamp of when consensus was reached. `null` if still pending or expired without consensus. **expires\_at** `string` ISO 8601 timestamp of when the witness request expires (or expired). ### Consensus Logic | Scenario | Outcome | | :- | :- | | Quorum met, majority `confirm` | `confirmed` | | Quorum met, majority `deny` | `denied` | | Quorum met, equal `confirm`/`deny` | Weighted by confidence scores; highest aggregate confidence wins | | TTL expires before quorum | `expired` | # Create Witness Request Source: https://docs.truthlocks.com/api-reference/machine-identity/witness/create mint-openapi.yaml POST /v1/witness/request Initiate a multi-agent witness verification for a truth claim Creates a new witness request that coordinates multiple independent machine agents to verify a truth claim. Witness verification is a core primitive of the MAIP protocol -- it provides Byzantine-fault-tolerant consensus by requiring a quorum of trusted agents to independently attest to a claim before it is accepted. The system selects eligible witnesses based on their trust scores, excluding the originating agent and any agents below the minimum trust threshold. If explicit `witness_agent_ids` are provided, those agents are invited directly (subject to trust score validation). ### Authentication Requires `X-API-Key` header or Bearer JWT token. The workspace is derived from the authenticated credential; do not send `X-Tenant-ID`. ### Response **id** `string` Unique identifier for the witness request. Format: `maip-wit:ULID`. **claim\_id** `string` The truth claim being witnessed. **status** `string` Initial status of the witness request. Always `pending` on creation. **required\_witnesses** `integer` Number of attestations needed to reach consensus. **current\_witnesses** `integer` Number of attestations received so far. `0` on creation. **expires\_at** `string` ISO 8601 timestamp when the witness request will expire if consensus is not reached. **created\_at** `string` ISO 8601 timestamp of creation. ### Witness Lifecycle | Status | Description | | :- | :- | | `pending` | Created, awaiting witness attestations | | `confirmed` | Quorum reached with majority `confirm` verdicts | | `denied` | Quorum reached with majority `deny` verdicts | | `expired` | TTL elapsed without reaching consensus | # Create Workflow Source: https://docs.truthlocks.com/api-reference/machine-identity/workflows/create mint-openapi.yaml POST /v1/orchestrate/workflows Create a workflow definition as a directed acyclic graph (DAG) of steps for repeatable AI orchestrations. Creates a new workflow definition. Workflows define a directed acyclic graph (DAG) of steps that orchestrations execute in sequence. Each step specifies its type, configuration, and dependencies -- enabling complex multi-step AI pipelines with deterministic execution order. Workflows are created in `draft` status and must be published before they can be executed. This two-phase approach allows teams to review and validate workflow definitions before they are available to agents. ### Response **id** `string` Unique workflow identifier. **name** `string` Workflow name. **description** `string` Workflow description. **version** `string` Workflow version. **steps** `array` The validated workflow step definitions. **status** `string` Workflow status. Always `draft` on creation. **created\_at** `string` ISO 8601 timestamp of creation. # Create a MAIP Workflow Run Record Source: https://docs.truthlocks.com/api-reference/machine-identity/workflows/execute mint-openapi.yaml POST /v1/orchestrate/workflows/{workflowId}/execute Records a run against a registered MAIP workflow. Records a run against a registered MAIP workflow. Supply `trigger_agent_id`, with optional `input_payload` and `metadata`. The current handler creates a run with status `running` and returns HTTP 201. This MAIP tracking route does not itself launch a Temporal workflow. Do not interpret the initial status as proof that workflow steps executed. New automatically generated receipts use the managed signer. Verify each receipt; a signature on the recorded request does not establish that workflow steps executed. Preserved historical placeholder signatures may remain unverifiable. Use the generated parameter fields above for the request contract. Authenticate with a credential for the target workspace and environment; do not supply a tenant-selection header. # List machine observability events Source: https://docs.truthlocks.com/api-reference/observability/events mint-openapi.yaml GET /v1/events List Observability Events Use the supported identity, event and time filters to inspect recorded machine activity. Keep pagination metadata when fetching additional records. Observability events are separate from the platform audit chain. # Create policy Source: https://docs.truthlocks.com/api-reference/policies/create mint-openapi.yaml POST /v1/policies Create a new issuance policy with rules that control minting, verification, or proof-bundle export. Creates a policy for the authenticated tenant. Set `status` to `DRAFT` to save without enforcing, or `ACTIVE` to begin enforcement immediately. Each policy contains a set of rules evaluated in order. The first matching rule determines the outcome. If no rule matches, the `default_effect` applies. > [!NOTE] > > See the [issuance policies guide](/guides/issuance-policies) for a walkthrough of rule syntax, condition operators, and lifecycle management. ### Responses # Delete policy Source: https://docs.truthlocks.com/api-reference/policies/delete mint-openapi.yaml DELETE /v1/policies/{id} Permanently remove a policy and its bindings. Deletes a policy and all associated bindings for the authenticated tenant. This action takes effect immediately — any requests that were subject to the policy will no longer be evaluated against it. > [!WARNING] > > Deleting a policy is irreversible. If you want to temporarily stop enforcement, set the policy status to `DISABLED` instead. See [policy lifecycle](/guides/issuance-policies#policy-lifecycle). ### Responses # Evaluate policy Source: https://docs.truthlocks.com/api-reference/policies/evaluate mint-openapi.yaml POST /v1/policies/evaluate Simulate a policy evaluation against a sample input to test rules before enforcing them. Evaluates all active policies that match the given action and target against the provided input. Use this endpoint to test how your policies behave before activating them in production. The response includes which rules matched, whether the request would be allowed, and a `decision_id` for audit trail queries. > [!NOTE] > > The `reasons` field is only populated when the request is denied. Allowed responses return an empty array. If you previously relied on `evaluation_ms` for performance monitoring, that field has been removed — query `resource_type=policy_decision` in the [decision audit trail](/security/audit#policy-decision-audit-trail) instead. > [!NOTE] > > Every evaluation is recorded in the audit log with a SHA-256 hash of the input for tamper-evidence. Use the `decision_id` to look up the decision in [audit queries](/security/audit). ### Responses ### Response fields | Field | Type | Description | | :- | :- | :- | | `allowed` | boolean | Whether the request would be permitted under the current active policies. | | `matched_rules` | string\[] | IDs of rules that matched the input. Empty when no rule matched and the default effect applied. | | `reasons` | string\[] | Explanation of why the request was denied. Always an empty array when `allowed` is `true`. | | `decision_id` | string | Unique identifier for this evaluation. Use it to look up the full decision record in the [audit trail](/security/audit#policy-decision-audit-trail). | # List policies Source: https://docs.truthlocks.com/api-reference/policies/list mint-openapi.yaml GET /v1/policies Retrieve all policies for the authenticated tenant. Returns an array of all policies for the current tenant, ordered by creation date (newest first). The response includes policies in all statuses — `DRAFT`, `ACTIVE`, and `DISABLED`. ### Responses # Create Receipt Type Source: https://docs.truthlocks.com/api-reference/receipts/create-type mint-openapi.yaml POST /v1/receipt-types Registers a custom receipt type with a JSON Schema for payload validation. Creates a tenant-custom receipt type with a JSON Schema for payload validation. Platform-defined types (`payment_receipt`, `security_event_receipt`, `delivery_receipt`, `compliance_receipt`, `custom_receipt`) are read-only and cannot be overridden or replaced. Custom types are isolated to the authenticated tenant by row-level security. Other tenants cannot see or use your custom types. ## Request body | Field | Type | Required | Description | | - | - | - | - | | `name` | string | Yes | Unique snake\_case identifier (e.g. `invoice_receipt`). Must not conflict with platform type names. | | `display_name` | string | Yes | Human-readable label shown in the console UI. | | `version` | string | No | SemVer string (default `1.0.0`). Create multiple versions to manage schema evolution. | | `schema` | object | Yes | Valid JSON Schema (draft 2020-12) describing the required `payload` structure. | | `description` | string | No | Plain-text description for documentation. | ### Schema Requirements The `schema` field must be a valid JSON Schema (draft 2020-12). Include a `required` array to enforce mandatory payload fields when minting. ```json theme={null} { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "required": ["invoice_number", "amount", "currency"], "properties": { "invoice_number": { "type": "string" }, "amount": { "type": "integer", "description": "Amount in smallest currency unit" }, "currency": { "type": "string", "minLength": 3, "maxLength": 3 } }, "additionalProperties": false } ``` ### Versioning Create multiple versions of the same type by passing different `version` values (`1.0.0`, `2.0.0`, etc.). Receipts always pin the version at mint time so existing receipts are unaffected when you introduce a new version. To deprecate an old version, use `PATCH /v1/receipt-types/{name}` with `{"status": "deprecated"}`. ### Responses # Export Receipts Source: https://docs.truthlocks.com/api-reference/receipts/export mint-openapi.yaml POST /v1/receipts/export Queue a bulk export and download receipts as JSON or CSV. Queues an async bulk export job. Returns immediately with `status: pending`. Poll `GET /v1/receipt-exports/{id}` for completion and a pre-signed download URL. ## Response **export\_id** `string` UUID of the export job. **status** `string` `pending` | `running` | `complete` | `failed` **format** `string` Requested format (`json` or `csv`). **created\_at** `string` ISO 8601 timestamp. ## Polling for completion Poll `GET /v1/receipt-exports/{export_id}` until `status` is `complete`. The response will include a pre-signed `download_url`. > [!NOTE] > > This endpoint moved from `/v1/receipts/export/{id}` to `/v1/receipt-exports/{id}`. Update any polling URLs that use the old path. ### Export status values | Status | Meaning | | - | - | | `pending` | Queued, not yet started | | `running` | Processing records | | `complete` | Done — `download_url` is available | | `failed` | Error — see `error_message` | # Get Receipt Source: https://docs.truthlocks.com/api-reference/receipts/get mint-openapi.yaml GET /v1/receipts/{id} Retrieve a receipt event by ID with full signature and log anchor. Retrieves a receipt event by ID. Returns the full receipt record including the cryptographic signature and transparency log anchor. ## Response **receipt\_id** `string` UUID of the receipt. **receipt\_type** `string` The receipt type name. **status** `string` `active`, `revoked`, `superseded`, or `redacted`. **issuer\_id** `string` UUID of the signing issuer. **subject** `string` Subject identifier. **payload** `object` The receipt payload. **signature** `object` Cryptographic signature details. **transparency\_log** `object` Merkle inclusion proof from the transparency log. **issued\_at** `string` ISO 8601 timestamp. # Get receipt type Source: https://docs.truthlocks.com/api-reference/receipts/get-type mint-openapi.yaml GET /v1/receipt-types/{name} Retrieves a single receipt type by name. Retrieves a single receipt type by name. Returns the full type definition including the JSON Schema used to validate the `payload` field when minting receipts of this type. To pin a specific version, append `@` to the name — for example, `payment_receipt@1.0.0`. ### Responses # List Receipts Source: https://docs.truthlocks.com/api-reference/receipts/list mint-openapi.yaml GET /v1/receipts Returns a paginated list of receipt events for the authenticated tenant. Returns a paginated list of receipt events for the authenticated tenant. Filter by type, status, or issuer. ## Response **items** `array` Array of receipt objects. **total** `integer` Total matching receipts. **limit** `integer` Page size. **offset** `integer` Current offset. # List receipt types Source: https://docs.truthlocks.com/api-reference/receipts/list-types mint-openapi.yaml GET /v1/receipt-types Returns all registered receipt types for the authenticated tenant. Returns all receipt types available to the authenticated tenant. Includes all five platform-defined types (globally available to every tenant) plus any custom types registered by the tenant. Use this endpoint to discover available types and inspect the JSON Schema each type enforces on the `payload` field when minting a receipt. ## Platform-defined types | Name | Display Name | Use Case | | - | - | - | | `payment_receipt` | Payment Receipt | Payments, invoices, refunds | | `security_event_receipt` | Security Event Receipt | Auth events, key rotations, anomalies | | `delivery_receipt` | Delivery Receipt | Document/credential/notification delivery | | `compliance_receipt` | Compliance Receipt | KYC, AML, sanctions checks | | `custom_receipt` | Custom Receipt | Any tenant-defined event (open schema) | Platform types have `tenant_id: null` in the response. Tenant-custom types include their `tenant_id`. ### Responses # Mint Receipt Source: https://docs.truthlocks.com/api-reference/receipts/mint mint-openapi.yaml POST /v1/receipts Create a cryptographically signed, transparency-log-anchored receipt event. Creates a cryptographically signed, transparency-log-anchored receipt event. Receipts are validated against the registered receipt type schema before signing. ### Receipt types | Type | Name | Required Fields | | - | - | - | | `payment_receipt` | Payment Receipt | `amount`, `currency`, `provider`, `provider_reference`, `subject` | | `security_event_receipt` | Security Event Receipt | `event_type`, `severity`, `subject`, `outcome` | | `delivery_receipt` | Delivery Receipt | `item_reference`, `recipient`, `delivery_method`, `delivered_at` | | `compliance_receipt` | Compliance Receipt | `check_type`, `subject`, `result`, `framework` | | `custom_receipt` | Custom Receipt | `subject`, `event` | ## Headers ## Response **receipt\_id** `string` UUID of the created receipt. **receipt\_type** `string` The receipt type name. **status** `string` `active` **issuer\_id** `string` UUID of the signing issuer. **subject** `string` Subject identifier. **signature** `object` Cryptographic signature: `alg`, `kid`, `value`. **issued\_at** `string` ISO 8601 timestamp. ### Webhook event A `receipt.created` webhook event is delivered to all configured endpoints after a successful mint. # Receipt Proof Bundle Source: https://docs.truthlocks.com/api-reference/receipts/proof-bundle mint-openapi.yaml GET /v1/receipts/{id}/proof-bundle Download a self-contained proof bundle for offline receipt verification. Returns a self-contained proof bundle for a receipt event. The bundle includes the signed receipt envelope, Merkle inclusion proof from the transparency log, and the issuer key snapshot at time of issuance. The bundle can be used for offline verification — no server call required after download. ## Response **bundle\_id** `string` UUID of the proof bundle. **bundle\_version** `string` Bundle format version (e.g. `receipt-v1`). **receipt** `object` Signed receipt envelope with `receipt_id`, `receipt_type`, and `signature`. **key** `object` Issuer key snapshot: `public_key_b64url`, `status`, `compromised_at`. **transparency\_log** `object` Merkle inclusion proof and checkpoint. **bundle\_hash\_b64url** `string` SHA-256 hash of the entire bundle. # Redact Receipt Source: https://docs.truthlocks.com/api-reference/receipts/redact mint-openapi.yaml POST /v1/receipts/{id}/redact Remove PII from a receipt payload while preserving cryptographic proof. Removes PII from a receipt's payload while preserving the cryptographic proof. The receipt's signature, transparency log entry, and Merkle inclusion proof remain intact — only the `payload_json` is replaced with a redaction marker. Use this for GDPR right-to-erasure requests on receipts containing personal data. > [!WARNING] > > Redaction is permanent. The original payload cannot be restored. The cryptographic proof remains valid for audit purposes. ## Headers ## Response **receipt\_id** `string` UUID of the redacted receipt. **status** `string` `redacted` **redacted\_at** `string` ISO 8601 timestamp of redaction. ### What changes after redaction * `status` → `redacted` * `payload_json` → `{"redacted": true, "redacted_by": "tenant_request"}` * A `RECEIPT_REDACT` event is anchored in the transparency log * All other fields (signature, log proof, receipt\_type) are preserved # Revoke Receipt Source: https://docs.truthlocks.com/api-reference/receipts/revoke mint-openapi.yaml POST /v1/receipts/{id}/revoke Revoke a receipt and record the event in the transparency log. Revokes a receipt event. Sets the status to `revoked` and records a `RECEIPT_REVOKE` event in the transparency log. Only `active` receipts can be revoked. ## Headers ## Response **receipt\_id** `string` UUID of the revoked receipt. **status** `string` `revoked` **revoked\_at** `string` ISO 8601 timestamp of revocation. ### Webhook event A `receipt.revoked` webhook event is delivered after successful revocation: ```json theme={null} { "event_type": "receipt.revoked", "receipt_id": "", "receipt_type": "payment_receipt", "tenant_id": "", "revoked_at": "" } ``` > [!NOTE] > > Revocation is permanent and recorded in the transparency log. # Search Receipts Source: https://docs.truthlocks.com/api-reference/receipts/search mint-openapi.yaml POST /v1/receipts/search Search receipts using full-text search and faceted filters. Search receipts using full-text search and faceted filters. Combine a text query with structured filters to narrow results. ## Response **items** `array` Array of matching receipt objects. **total** `integer` Total number of matching receipts. **limit** `integer` Page size used. **offset** `integer` Current offset. # Set Signing Policy Source: https://docs.truthlocks.com/api-reference/receipts/signing-policy mint-openapi.yaml POST /v1/receipt-types/{name}/signing-policy Configure which issuers and algorithms may sign receipts of a given type. Sets or updates the signing policy for a receipt type. The policy controls which issuers can mint receipts and which signing algorithms are permitted. If no policy is configured, all trusted issuers with any algorithm are permitted. To read the current policy, use `GET /v1/receipt-types/{name}/signing-policy`. ## Response **receipt\_type** `string` The receipt type name. **allow\_any\_issuer** `boolean` Whether any trusted issuer can mint. **allowed\_issuer\_ids** `array` Whitelisted issuer UUIDs. **min\_trust\_tier** `string` Minimum trust tier required. **allowed\_algs** `array` Permitted signing algorithms. **updated\_at** `string` ISO 8601 timestamp of last update. # Verify Receipt Source: https://docs.truthlocks.com/api-reference/receipts/verify mint-openapi.yaml POST /v1/receipts/verify Verify a receipt's cryptographic signature and current status. Verifies a receipt by ID. Returns a verdict indicating the cryptographic validity and current status of the receipt. ### Verdicts | Verdict | Meaning | | - | - | | `VALID` | Signature is valid, key was not compromised, receipt is active | | `REVOKED` | Receipt has been explicitly revoked | | `INVALID_SIGNATURE` | Cryptographic signature verification failed | | `KEY_COMPROMISED` | Signing key was marked compromised at or before issuance | | `KEY_INACTIVE` | Signing key is no longer active | | `NOT_FOUND` | Receipt not found for this tenant | ## Response **receipt\_id** `string` UUID of the verified receipt. **verdict** `string` `VALID`, `REVOKED`, `INVALID_SIGNATURE`, `KEY_COMPROMISED`, `KEY_INACTIVE`, or `NOT_FOUND`. **receipt\_type** `string` The receipt type name. **issuer\_id** `string` UUID of the issuer that signed the receipt. **issued\_at** `string` ISO 8601 timestamp of when the receipt was minted. **verified\_at** `string` ISO 8601 timestamp of this verification check. # Get risk signal Source: https://docs.truthlocks.com/api-reference/risk-signals/get mint-openapi.yaml GET /v1/risk/signals/{id} Retrieves a specific risk signal by its unique ID. Retrieves a specific risk signal by its unique ID. Returns the full signal record including source, score, subject reference, and any attached metadata. # List risk signals Source: https://docs.truthlocks.com/api-reference/risk-signals/list mint-openapi.yaml GET /v1/risk/signals Returns risk signals for the authenticated tenant with pagination. Filter by source, signal type, entity, or minimum score. Returns risk signals for the authenticated tenant with cursor-based pagination. Use query parameters to filter by source, signal type, subject, or minimum risk score. # List ATO alerts Source: https://docs.truthlocks.com/api-reference/risk/ato-alerts mint-openapi.yaml GET /v1/risk/ato/alerts List account takeover alerts triggered by the ATO heuristic engine. Alerts are created automatically when a subject crosses a risk threshold. Returns a paginated list of ATO alerts for your tenant. Alerts are created automatically when the [ATO evaluation endpoint](/api-reference/risk/ato-evaluate) detects that a subject has crossed a risk threshold. Each alert includes the subject, alert type, risk level at the time of triggering, and a reference to the auto-ingested risk signal. See the [account takeover detection guide](/guides/ato-detection) for the full workflow. ## Response **alerts** `array` Array of alert objects. **alerts\[].alert\_id** `string` UUID of the alert. **alerts\[].subject\_id** `string` The subject that triggered the alert. **alerts\[].alert\_type** `string` Alert category: `velocity_exceeded` or `credential_stuffing`. **alerts\[].risk\_level** `string` Risk level when the alert was created: `elevated` | `high` | `critical` **alerts\[].risk\_score** `integer` Risk score when the alert was created. **alerts\[].signal\_id** `string` UUID of the auto-ingested risk signal linked to this alert. **alerts\[].created\_at** `string` ISO 8601 timestamp of when the alert was created. **next\_cursor** `string` Cursor for the next page of results. `null` when there are no more results. # Evaluate ATO risk Source: https://docs.truthlocks.com/api-reference/risk/ato-evaluate mint-openapi.yaml POST /v1/risk/ato/evaluate Evaluate a login event against account takeover heuristics. Tracks failed login velocity per subject and triggers alerts when thresholds are exceeded. Evaluates a login event against the ATO heuristic engine. The platform tracks failed logins per subject in a rolling one-hour window and derives a risk level from the current count. When a threshold is crossed, an alert is created and a risk signal is automatically ingested into the [risk signal pipeline](/guides/risk-signals). See the [account takeover detection guide](/guides/ato-detection) for the full workflow, threshold reference, and integration patterns. ## Threshold rules | Failed logins (1 h window) | Risk level | Auto-alert | | :- | :- | :- | | 0–4 | normal | No | | 5–9 | elevated | Yes — `velocity_exceeded` | | 10–19 | high | Yes — `velocity_exceeded` | | 20+ | critical | Yes — `credential_stuffing` | ## Response **subject\_id** `string` The subject that was evaluated. **subject\_type** `string` Type of subject (`user`). **risk\_level** `string` Current ATO risk level: `normal` | `elevated` | `high` | `critical` **risk\_score** `integer` Numeric risk score: 10 (normal), 50 (elevated), 70 (high), 90 (critical). **failed\_login\_count** `integer` Number of failed logins in the current one-hour window. **alert** `boolean` `true` if a new alert was triggered by this evaluation. **alert\_type** `string` Alert category when triggered: `velocity_exceeded` or `credential_stuffing`. **signal\_id** `string` UUID of the auto-ingested risk signal (only present when an alert fired). **event\_type** `string` The event type that was evaluated. # Get ATO profile Source: https://docs.truthlocks.com/api-reference/risk/ato-profile mint-openapi.yaml GET /v1/risk/ato/profile/{subject_id} Retrieve the current account takeover risk profile for a subject, including failed login count, risk level, and known devices. Returns the ATO risk profile for the specified subject. The profile tracks failed login velocity in a rolling one-hour window and records known IP addresses and devices. Use this endpoint to check the current risk posture of a user without triggering a new evaluation. See the [account takeover detection guide](/guides/ato-detection) for the full workflow. ## Response **subject\_id** `string` The subject identifier. **subject\_type** `string` Type of subject (`user`). **risk\_level** `string` Current ATO risk level: `normal` | `elevated` | `high` | `critical` **failed\_login\_count** `integer` Number of failed logins in the current one-hour window. **known\_ips** `array` List of IP addresses previously seen for this subject. **known\_devices** `array` List of device identifiers previously seen for this subject. **updated\_at** `string` ISO 8601 timestamp of the last profile update. # Record a block decision Source: https://docs.truthlocks.com/api-reference/risk/block mint-openapi.yaml POST /v1/risk/block Block a subject Provide a subject\_id and a reason of at least ten characters. The server records a block decision and active quarantine for the subject/type. Your application must enforce that decision where it grants access; this endpoint does not reconfigure an external firewall. # Record a challenge decision Source: https://docs.truthlocks.com/api-reference/risk/challenge mint-openapi.yaml POST /v1/risk/challenge Challenge a subject The server records that a subject needs a challenge and returns challenge\_required. It does not collect identity evidence or send a challenge automatically. Route the subject through the verification process you implement and retain the decision identifier. # Read risk settings Source: https://docs.truthlocks.com/api-reference/risk/config/get mint-openapi.yaml GET /v1/risk/config Get risk configuration Read stored thresholds and notification preferences. An empty updated\_at means defaults have not yet been persisted. A notification switch does not prove that an email or webhook was delivered. # Update risk settings Source: https://docs.truthlocks.com/api-reference/risk/config/update mint-openapi.yaml PUT /v1/risk/config Update risk configuration Send only supported fields shown in Try It. Thresholds accept 0 through 100. Omitted values retain their stored settings, or use defaults on first save. Configure and test actual delivery separately from notification preferences. # Read risk overview metrics Source: https://docs.truthlocks.com/api-reference/risk/dashboard/metrics mint-openapi.yaml GET /v1/risk/dashboard/metrics Dashboard metrics Read aggregate workspace counts and the dedicated signals\_24h and signals\_7d fields. This endpoint does not implement a general period query parameter. Risk scores summarize recorded signals rather than certifying identity or legal compliance. # Read most active risk subjects Source: https://docs.truthlocks.com/api-reference/risk/dashboard/top-subjects mint-openapi.yaml GET /v1/risk/dashboard/top-subjects Top risk subjects Returns up to 100 subjects ordered by signal count and then maximum score. It is not a ranking by average risk, and period or sort\_by overrides are not implemented. A null latest\_decision means no decision was returned for that subject/type. # Read risk trends Source: https://docs.truthlocks.com/api-reference/risk/dashboard/trends mint-openapi.yaml GET /v1/risk/dashboard/trends Dashboard trends Choose 24h, 7d, 30d or 90d. The server selects the matching bucket size; a granularity override is not implemented. Inspect both signal and decision counts when comparing activity. # List risk decisions Source: https://docs.truthlocks.com/api-reference/risk/decisions mint-openapi.yaml GET /v1/risk/decisions List risk decisions Filter by subject\_id or decision and paginate with limit and offset. The endpoint uses offset pagination, not a cursor. A recorded decision describes the risk workflow; it is not proof that an external application applied enforcement. # Get deepfake scan results Source: https://docs.truthlocks.com/api-reference/risk/deepfake-results mint-openapi.yaml GET /v1/risk/deepfake/results/{subject_ref} Retrieve the most recent deepfake and impersonation scan result for a given subject reference. Returns the latest scan result for the specified `subject_ref`. Use this to check the current deepfake and impersonation status of a previously scanned subject without re-running the scan. ## Response **scan\_id** `string` UUID of the scan result. **subject\_ref** `string` The subject reference that was scanned. **subject\_type** `string` Type of subject: `image`, `video`, `document`, `attestation`, `identity` **deepfake\_score** `integer` Deepfake probability score (0–100). **impersonation\_score** `integer` Impersonation probability score (0–100). **verdict** `string` `authentic` | `suspect` | `deepfake` | `impersonation` **indicators** `array` List of triggered indicators from the scan. **detection\_model** `string` Detection model used (e.g. `heuristic_v1`). **signal\_id** `string` UUID of the auto-ingested risk signal, if the score met the threshold (≥ 60). **attestation\_id** `string` UUID of the linked attestation, if one was provided during the scan. **created\_at** `string` ISO 8601 timestamp of when the scan was performed. # Deepfake & impersonation scan Source: https://docs.truthlocks.com/api-reference/risk/deepfake-scan mint-openapi.yaml POST /v1/risk/deepfake/scan Submit a subject for deepfake and impersonation analysis. Returns scores, verdict, and indicators. Automatically ingests a risk signal if scores exceed the auto-trigger threshold (60). > [!WARNING] > > This endpoint does not download or inspect the referenced image, video, or document. It scores indicators or scores supplied by your application. Values are heuristic risk scores, not calibrated probabilities. The `authentic` label means the configured risk threshold was not reached; it is not proof that media is authentic, especially when no indicators were supplied. ## How detection works Scans use a **heuristic signal engine** (`heuristic_v1`) that accepts caller-provided signals (from external ML models, rule engines, or manual review) and maps them to weighted scores: * **Deepfake indicators:** face swap, inconsistent lighting, compression artifacts, temporal inconsistency, metadata mismatch * **Impersonation indicators:** biometric mismatch, name mismatch, identity doc mismatch, issuer trust violation Scores ≥ 75 set verdict `deepfake` or `impersonation`. Scores ≥ 40 set `suspect`. Scores ≥ 60 automatically ingest a risk signal. You can also bypass heuristic analysis by passing pre-computed `deepfake_score` and `impersonation_score` values directly. The platform still applies the same verdict thresholds and automatic signal ingestion. See the [deepfake detection guide](/guides/deepfake-detection) for the full workflow, indicator reference, and additional examples. ## Response **scan\_id** `string` UUID of the scan result. **subject\_ref** `string` The subject reference that was scanned. **subject\_type** `string` Type of subject: `image`, `video`, `document`, `attestation`, `identity` **deepfake\_score** `integer` Deepfake heuristic risk score (0–100). **impersonation\_score** `integer` Impersonation heuristic risk score (0–100). **verdict** `string` `authentic` | `suspect` | `deepfake` | `impersonation` **indicators** `array` List of triggered indicators from the scan. **detection\_model** `string` Detection model used (e.g. `heuristic_v1`). **signal\_id** `string` UUID of the auto-ingested risk signal (only present when score ≥ 60). **attestation\_id** `string` UUID of the linked attestation, if one was provided during the scan. **created\_at** `string` ISO 8601 timestamp of when the scan was performed. # Risk Evaluate Source: https://docs.truthlocks.com/api-reference/risk/evaluate mint-openapi.yaml POST /v1/risk/evaluate Unified risk evaluation endpoint. Ingests a signal, evaluates it against your tenant policies, creates a signed risk decision, and optionally mints a fraud_decision_receipt for non-repudiation. ## How Evaluation Works 1. The signal is ingested into `risk_signals` 2. Your active policy rules are evaluated (highest priority match wins) 3. A `risk_decision` record is created with the outcome 4. If `mint_receipt: true` and `issuer_id`/`kid` are provided, a `fraud_decision_receipt` is minted via the attestation service ## Decision Outcomes | Action | Meaning | | - | - | | `allow` | No policy matched or score below all thresholds | | `challenge` | MFA or step-up authentication required | | `block` | Reject the action entirely | | `review` | Route to manual fraud review queue | ## Built-in receipt types | Receipt Type | Purpose | | - | - | | `fraud_decision_receipt` | Records allow/challenge/block/review decision | | `ato_alert_receipt` | Records ATO alert events | | `risk_block_receipt` | Proves an action was blocked | | `deepfake_detection_receipt` | Records deepfake scan results | ## Response **decision** `string` `allow` | `challenge` | `block` | `review` **decision\_id** `string` UUID of the risk decision record. **signal\_id** `string` UUID of the ingested risk signal. **policy\_id** `string` UUID of the matching policy rule (if any). **receipt\_id** `string` UUID of the minted receipt (only if `mint_receipt: true` and succeeded). # Create risk-event export Source: https://docs.truthlocks.com/api-reference/risk/exports/create mint-openapi.yaml POST /v1/risk/siem/export Persist a filtered snapshot job for JSON, CSV, CEF or LEEF. Submit an object such as `{ "format": "json", "event_types": ["signal", "decision"] }`. Save `export_id` and poll the read endpoint. A 202 response confirms that the job exists; it does not confirm that processing is complete. Risk exports contain workspace risk signals and decisions. They do not configure automatic audit-log forwarding. See [SIEM integration](/guides/siem-integration) for the distinction. # Delete risk-event export Source: https://docs.truthlocks.com/api-reference/risk/exports/delete mint-openapi.yaml DELETE /v1/risk/siem/export/{id} Remove an export snapshot while preserving its source records. Supply the `export_id` as the path parameter. A 204 response has no body. This deletes the generated copy and job only; source risk signals and decisions remain under their own retention rules. Risk exports contain workspace risk signals and decisions. They do not configure automatic audit-log forwarding. See [SIEM integration](/guides/siem-integration) for the distinction. # Read risk-event export Source: https://docs.truthlocks.com/api-reference/risk/exports/get mint-openapi.yaml GET /v1/risk/siem/export/{id} Poll an export and retrieve its completed evidence. Supply the `export_id` from creation as the path parameter. No request body is required. Polling resumes pending work after a restart. Read `status` before consuming `export_data`; a failed job includes an explanation. If the window contains more than 10,000 records, create a new export with a narrower date range. Risk exports contain workspace risk signals and decisions. They do not configure automatic audit-log forwarding. See [SIEM integration](/guides/siem-integration) for the distinction. # Ingest Risk Signal Source: https://docs.truthlocks.com/api-reference/risk/ingest-signal mint-openapi.yaml POST /v1/risk/signals Ingest a raw risk signal event. Risk signals are the foundation of the Anti-Fraud Identity Firewall — they represent a single suspicious observation about a subject. ## Headers ## Response **signal\_id** `string` UUID of the created risk signal. **risk\_score** `integer` The ingested risk score (0–100). **created\_at** `string` ISO 8601 timestamp of ingestion. # Normalize Identity Event Source: https://docs.truthlocks.com/api-reference/risk/normalize-event mint-openapi.yaml POST /v1/risk/events Submit a raw identity event for automatic normalization into a risk signal. The normalization layer maps platform events to standardized signal types with pre-calibrated risk scores. ## How Normalization Works When you submit an identity event, the platform: 1. Records the raw event in the audit trail 2. Maps the `event_type` to a canonical signal type and base risk score 3. Enriches the signal with available metadata (issuer trust tier, geo, device) 4. Stores a `risk_signal` record ready for policy evaluation ### Built-in Event Mappings | Event Type | Signal Type | Base Score | | - | - | - | | `verification.failed` | behavior | 60 | | `verification.invalid_sig` | behavior | 75 | | `login.failed.repeated` | ato | 70 | | `login.suspicious_geo` | geo\_anomaly | 65 | | `attestation.deepfake_suspect` | deepfake | 85 | | `session.hijack_suspect` | ato | 90 | Unknown event types are accepted with a base score of 10 and signal type `behavior`. ## Response **event\_id** `string` UUID of the recorded raw event source. **signal\_id** `string` UUID of the normalized risk signal created from this event. **signal\_type** `string` The normalized signal type derived from the event. **risk\_score** `integer` The base risk score assigned during normalization. **normalized** `boolean` `true` if the event matched a known mapping; `false` if it used the generic fallback. # Read subject quarantine Source: https://docs.truthlocks.com/api-reference/risk/quarantine/get mint-openapi.yaml GET /v1/risk/quarantine/{subject_id} Get quarantine status Supply the original subject identifier and matching subject\_type. The read reports active, unexpired quarantine. A false result does not imply that the subject passed identity review or has a low risk score. # Release subject quarantine Source: https://docs.truthlocks.com/api-reference/risk/quarantine/release mint-openapi.yaml DELETE /v1/risk/quarantine/{subject_id} Remove from quarantine Release the active quarantine for the subject/type after your review. Historical decisions remain available. Releasing quarantine does not automatically restore access in external systems. # List velocity anomalies Source: https://docs.truthlocks.com/api-reference/risk/velocity-anomalies mint-openapi.yaml GET /v1/risk/velocity List subjects with velocity scores above a threshold. Use this to identify high-velocity anomalies across your tenant. Returns a paginated list of subjects whose velocity score meets or exceeds the specified threshold. Use this endpoint to monitor for velocity anomalies across your tenant without querying individual subjects. Results are sorted by velocity score (highest first) and support cursor-based pagination. See the [velocity and anomaly scoring guide](/guides/velocity-scoring) for the scoring model and integration patterns. ## Response **anomalies** `array` List of subjects with elevated velocity scores. Each entry includes `subject_id`, `action_type`, `windows` (with `1m`, `5m`, `1h`, `24h` counts), `velocity_score`, and `last_recorded_at`. **cursor** `string` Pagination cursor for the next page. `null` when there are no more results. # Record velocity action Source: https://docs.truthlocks.com/api-reference/risk/velocity-record mint-openapi.yaml POST /v1/risk/velocity/record Record a subject action and evaluate it against velocity-based anomaly scoring. Auto-ingests a risk signal when the velocity score reaches 60 or above. Records an action for a subject and updates rolling window counters across four time windows (1 m, 5 m, 1 h, 24 h). A weighted velocity score is computed from the updated counts. When the score reaches 60 or above, a risk signal with `signal_type: "velocity"` is automatically ingested into the [risk signal pipeline](/guides/risk-signals). See the [velocity and anomaly scoring guide](/guides/velocity-scoring) for the full workflow, scoring model, and integration patterns. ## Scoring weights | Window | Weight | Purpose | | :- | :- | :- | | 1 minute | 30 | Burst detection | | 5 minutes | 20 | Sustained short-term abuse | | 1 hour | 10 | Medium-term patterns | | 24 hours | 5 | Persistent anomalies | ## Response **subject\_id** `string` The subject that was recorded. **action\_type** `string` The action type that was recorded. **windows** `object` Current action counts per rolling window: `1m`, `5m`, `1h`, `24h`. **velocity\_score** `integer` Weighted velocity score (0–100). Scores at or above 60 trigger automatic signal ingestion. **signal\_ingested** `boolean` `true` if a risk signal was auto-ingested because the velocity score reached 60 or above. **signal\_id** `string` UUID of the auto-ingested risk signal (only present when `signal_ingested` is `true`). # Get velocity windows Source: https://docs.truthlocks.com/api-reference/risk/velocity-windows mint-openapi.yaml GET /v1/risk/velocity/{subject_id} Retrieve current rolling window counts and velocity scores for all tracked action types of a subject. Returns the current velocity windows for a subject across all tracked action types. Each action type includes counts for the four rolling windows (1 m, 5 m, 1 h, 24 h) and the computed velocity score. Use this endpoint to check a subject's current velocity profile without recording a new action. See the [velocity and anomaly scoring guide](/guides/velocity-scoring) for the scoring model and integration patterns. ## Response **subject\_id** `string` The subject that was queried. **actions** `array` List of tracked action types for this subject. Each entry includes `action_type`, `windows` (with `1m`, `5m`, `1h`, `24h` counts), and `velocity_score`. # Request production activation Source: https://docs.truthlocks.com/api-reference/tenants/activate mint-openapi.yaml POST /v1/tenants/me/activate Activate tenant after onboarding No request body is required. The server checks production prerequisites and returns 412 when they are incomplete or 409 when the workspace is not awaiting activation. This is not an identity-approval shortcut. # Read workspace profile Source: https://docs.truthlocks.com/api-reference/tenants/get mint-openapi.yaml GET /v1/tenants/me Get current tenant profile Returns the workspace resolved from your authenticated identity. Use its status and onboarding fields when deciding which setup step to show; a profile read does not grant production access. # Update workspace profile Source: https://docs.truthlocks.com/api-reference/tenants/update mint-openapi.yaml PATCH /v1/tenants/me Update current tenant profile Include name, which the current endpoint requires even for a partial update. Supply slug only when changing it. Changing the profile country does not establish verified billing-country eligibility; paid billing uses its separate evidence review. # Invite User Source: https://docs.truthlocks.com/api-reference/users/invite mint-openapi.yaml POST /v1/users Invites a new user to the organization. Invites a new user to the organization. The user will receive an email with instructions to complete setup. ### Responses # List workspace users Source: https://docs.truthlocks.com/api-reference/users/list mint-openapi.yaml GET /v1/users List Users Returns users belonging to the authenticated organization with total, limit and offset. This is the organization directory, not the platform-wide administrative user list. # Download a document version Source: https://docs.truthlocks.com/api-reference/vault/download mint-openapi.yaml GET /v1/vault/documents/{id}/versions/{version}/download Requires a signed-in workspace member bearer session. API keys are not accepted. Workspace and environment come from the validated session. Changes require the workspace owner or administrator. Use a valid workspace bearer session. An API key cannot authorize this endpoint. The current workspace and environment are derived from that session. See [information handling](/enterprise/information-handling) for file limits, versioning, holds, retention and disposal behavior. # Get document versions and activity Source: https://docs.truthlocks.com/api-reference/vault/get mint-openapi.yaml GET /v1/vault/documents/{id} Requires a signed-in workspace member bearer session. API keys are not accepted. Workspace and environment come from the validated session. Changes require the workspace owner or administrator. Use a valid workspace bearer session. An API key cannot authorize this endpoint. The current workspace and environment are derived from that session. See [information handling](/enterprise/information-handling) for file limits, versioning, holds, retention and disposal behavior. # Change document retention or lifecycle Source: https://docs.truthlocks.com/api-reference/vault/lifecycle mint-openapi.yaml POST /v1/vault/documents/{id}/actions Requires a signed-in workspace member bearer session. API keys are not accepted. Workspace and environment come from the validated session. Changes require the workspace owner or administrator. Use a valid workspace bearer session. An API key cannot authorize this endpoint. The current workspace and environment are derived from that session. See [information handling](/enterprise/information-handling) for file limits, versioning, holds, retention and disposal behavior. # List workspace documents Source: https://docs.truthlocks.com/api-reference/vault/list mint-openapi.yaml GET /v1/vault/documents Requires a signed-in workspace member bearer session. API keys are not accepted. Workspace and environment come from the validated session. Changes require the workspace owner or administrator. Use a valid workspace bearer session. An API key cannot authorize this endpoint. The current workspace and environment are derived from that session. See [information handling](/enterprise/information-handling) for file limits, versioning, holds, retention and disposal behavior. # Upload a private document version Source: https://docs.truthlocks.com/api-reference/vault/upload mint-openapi.yaml POST /v1/vault/uploads Requires a signed-in workspace member bearer session. API keys are not accepted. Workspace and environment come from the validated session. Changes require the workspace owner or administrator. Use a valid workspace bearer session. An API key cannot authorize this endpoint. The current workspace and environment are derived from that session. See [information handling](/enterprise/information-handling) for file limits, versioning, holds, retention and disposal behavior. # Create Verification Pack Source: https://docs.truthlocks.com/api-reference/verification-packs/create mint-openapi.yaml POST /v1/attestation-packs Creates a new custom verification pack for the tenant. Creates a custom verification pack for the tenant. New packs start in 'draft' status and must be activated before attestations can be linked to them. Categories help organize packs by industry vertical. ### Responses # Get Verification Pack Source: https://docs.truthlocks.com/api-reference/verification-packs/get mint-openapi.yaml GET /v1/attestation-packs/{id} Returns details of a specific verification pack. Returns a single verification pack by ID, including its current verification count, status, and metadata. ### Responses # List Verification Packs Source: https://docs.truthlocks.com/api-reference/verification-packs/list mint-openapi.yaml GET /v1/attestation-packs Returns all verification packs for the authenticated tenant, including built-in enterprise templates and custom packs. Returns all verification packs for the authenticated tenant, including both built-in enterprise templates and custom packs. Templates are seeded automatically on first access. Results are ordered by template status (templates first) then by creation date descending. ### Responses # Update Verification Pack Source: https://docs.truthlocks.com/api-reference/verification-packs/update mint-openapi.yaml PUT /v1/attestation-packs/{id} Updates a verification pack's name, description, or configuration. Updates the name, description, and category of an existing verification pack. Only custom packs and templates can be edited. ### Responses # Update Pack Status Source: https://docs.truthlocks.com/api-reference/verification-packs/update-status mint-openapi.yaml PUT /v1/attestation-packs/{id}/status Activates, deactivates, or archives a verification pack. Changes the status of a verification pack. Valid transitions: draft → active (enables the pack for linking to attestations), active → archived (disables the pack, existing attestation links are preserved), archived → active (re-enables the pack). ### Responses # Verify Attestation Source: https://docs.truthlocks.com/api-reference/verify mint-openapi.yaml POST /v1/verify Check record status, issuer metadata and available evidence. Supply the exact original payload_b64url to verify the cryptographic signature. An ID-only or file-fingerprint-only lookup returns INCOMPLETE with signature_verified false if no stronger failure applies. VALID means the supplied payload passed signature checks; it does not prove the truth of the claims or guarantee that optional policy and transparency checks completed. Inspect reasons and log.proof_checked. Public requests need no API key; authenticated requests are scoped and metered against the caller's workspace. Check a record's current status and available evidence. To check its cryptographic signature, send the **exact original signed payload** as `payload_b64url`. A record ID or file fingerprint alone cannot supply those bytes. ### Choose the check you need | Input | What it checks | | - | - | | `attestation_id` | Finds an accessible record and checks its current status, issuer metadata and available log evidence. | | ID plus `payload_b64url` | Also checks the payload digest and signature against the registered public key. Encode the original bytes; reformatting JSON can change those bytes. | | ID plus `document_hash_hex` | Compares a supplied SHA-256 fingerprint with the recorded document fingerprint. This does not replace the signed-payload check. | An ID-only or fingerprint-only check returns `INCOMPLETE` and `signature_verified: false` unless a stronger result such as `REVOKED`, `EXPIRED`, or `ALTERED` applies. Supply the original payload for a complete signature check. An inline `attestation` must identify a registered record with `attestation_id`. Online status and key identity are loaded from that record; fields supplied by the caller cannot override its issuer or revocation. Use a compatible offline verifier for standalone signature checks. ### Interpret the response | Verdict | Meaning | | - | - | | `VALID` | The supplied payload passed its signature check and no blocking failure was returned. Inspect reasons and individual checks. | | `INCOMPLETE` | Required original content was not supplied; the signature was not checked. | | `ALTERED` | A supplied payload, signature or document fingerprint failed an integrity check. | | `REVOKED` | The record has been revoked. | | `SUPERSEDED` | A newer record replaces this one. Ask the issuer for its current record. | | `EXPIRED` | The record or signing key has expired. | | `INVALID` | A required input or verification check failed. | | `NOT_FOUND` | No accessible record matched the request and its environment. | | `UNKNOWN_ISSUER` | The issuer's signing key could not be accepted. | `signature_verified` reports the signature check specifically. `log.proof_checked` reports successful transparency inclusion checking. A missing proof produces a reason and a null leaf index; zero is a legitimate first leaf. An absent `expires_at_unix` value does not mean that a new expiry should be invented for a historical record. > [!WARNING] > > A valid signature does not prove ownership, legal validity, or the truth of every claim. Read `reasons`, current issuer governance, and the available evidence before relying on a record. Optional policy or log checks may be unavailable even when the payload signature passes. ### Authentication and limits Public verification does not require an API key. Authenticated calls use the caller's workspace and environment and may be subject to its verification allowance. Service rate limits still apply to public requests. A private or sandbox record may not be available through an anonymous production lookup. Share an accessible record using `https://verify.truthlocks.com/proof/{attestation_id}`. A shared URL does not grant access to private payloads. # Create webhook endpoint Source: https://docs.truthlocks.com/api-reference/webhooks/create-endpoint mint-openapi.yaml POST /v1/webhooks/endpoints Registers a new webhook endpoint for the authenticated tenant. Registers a new webhook endpoint for the authenticated tenant. The endpoint receives HTTP POST requests when matching events occur. The endpoint secret is returned once in the response — store it securely. > [!NOTE] > > The number of webhook endpoints you can create depends on your billing plan. If you exceed your plan limit, the API returns `402 Payment Required`. ### Responses > [!WARNING] > > The `secret` field is only returned in the creation response. Store it securely — you cannot retrieve it later. If you lose it, [rotate the secret](/api-reference/webhooks/rotate-secret) to generate a new one. # List deliveries Source: https://docs.truthlocks.com/api-reference/webhooks/list-deliveries mint-openapi.yaml GET /v1/webhooks/endpoints/{id}/deliveries Returns delivery history for a webhook endpoint. Returns the most recent delivery attempts for a webhook endpoint (up to 50). Use this to monitor delivery health, debug failures, and verify that events are reaching your server. ### Delivery statuses | Status | Description | | :- | :- | | `pending` | Delivery is queued and has not been attempted yet | | `delivered` | Your endpoint returned a 2xx status code | | `failed` | Delivery failed but may be retried | | `dead` | All retry attempts exhausted — delivery permanently failed | ### Response fields | Field | Type | Description | | :- | :- | :- | | `id` | `uuid` | Unique identifier for the delivery attempt | | `endpoint_id` | `uuid` | The webhook endpoint this delivery belongs to | | `event_id` | `string` | Unique event identifier — use this to deduplicate retried events | | `event_type` | `string` | Event type that triggered the delivery (e.g., `attestation.created`) | | `payload_hash` | `string` | SHA-256 hash of the delivered payload | | `status` | `string` | Current delivery status: `pending`, `delivered`, `failed`, or `dead` | | `attempt_count` | `integer` | Total number of delivery attempts so far | | `next_attempt_at` | `string` | ISO 8601 timestamp of the next retry, or `null` if no retry is scheduled | | `last_error` | `string` | Error message from the most recent failed attempt, or `null` if successful | | `http_status` | `integer` | HTTP status code returned by your endpoint, if available | | `created_at` | `string` | ISO 8601 timestamp when the delivery was first queued | | `updated_at` | `string` | ISO 8601 timestamp of the most recent status change | ### Responses > [!NOTE] > > Results are limited to the 50 most recent deliveries, sorted by creation time (newest first). Pagination is not currently supported. # List webhook endpoints Source: https://docs.truthlocks.com/api-reference/webhooks/list-endpoints mint-openapi.yaml GET /v1/webhooks/endpoints Returns all configured webhook endpoints for the authenticated tenant. Returns all webhook endpoints for the authenticated tenant, sorted by creation time (newest first). The endpoint `secret` is not included in list responses — it is only returned once when the endpoint is [created](/api-reference/webhooks/create-endpoint). ### Response fields | Field | Type | Description | | :- | :- | :- | | `id` | `uuid` | Unique identifier for the endpoint | | `name` | `string` | Human-readable name you assigned when creating the endpoint | | `url` | `string` | The HTTPS URL that receives webhook deliveries | | `status` | `string` | Current endpoint status: `active` or `disabled` | | `event_filters` | `string[]` | Event types or wildcard patterns the endpoint subscribes to | | `created_at` | `string` | ISO 8601 timestamp when the endpoint was created | | `updated_at` | `string` | ISO 8601 timestamp of the last modification | ### Responses # Rotate endpoint secret Source: https://docs.truthlocks.com/api-reference/webhooks/rotate-secret mint-openapi.yaml POST /v1/webhooks/endpoints/{id}/rotate Generates a new signing secret for the webhook endpoint. The old secret is immediately invalidated. Generates a new signing secret for a webhook endpoint. The old secret stops working immediately. The new secret is returned once — store it securely. > [!WARNING] > > Rotating the secret invalidates the previous secret immediately. Update your webhook verification code with the new secret before processing further events. ### Responses > [!TIP] > > After rotating, update your webhook verification code with the new secret immediately. Any deliveries signed with the old secret will fail verification. # Send test delivery Source: https://docs.truthlocks.com/api-reference/webhooks/test-delivery mint-openapi.yaml POST /v1/webhooks/test-delivery Sends a test event to a webhook endpoint to verify connectivity. Sends a test event to a webhook endpoint using the full signing and delivery pipeline. Use this to verify that your endpoint is reachable and correctly verifying signatures before subscribing to real events. A confirmation email is sent to the authenticated user on success. ### Responses The response tells you whether the test delivery reached your endpoint and what HTTP status code it returned. > [!TIP] > > Use the test delivery endpoint during development to confirm your signature verification logic works correctly before going live. The test event goes through the same signing pipeline as real events. # Billing System Source: https://docs.truthlocks.com/billing/overview Pay-per-use pricing, plan tiers, and usage management for your Truthlocks organization. Truthlocks uses a pay-per-use billing model where you only pay for what you consume. Every organization (tenant) has its own subscription, usage counters, and billing cycle. Features and quotas are enforced based on your active plan. ## Plan tiers * **Tenant-Centric**: Each tenant (Organization) has its own subscription and billing cycle. * **Entitlements**: Features and quotas are enforced based on the active plan key (`plan_developer`, `plan_starter`, `plan_business`, `plan_institutional`, `plan_enterprise`). * **Multi-Provider**: We route payments through different gateways (Stripe, Paystack, Flutterwave) depending on the tenant's legal jurisdiction. * **Regional Pricing**: Checkout automatically uses your account's country to apply the correct regional rates and currency. See [provider routing](/billing/provider-routing) for details. ## Plan Tiers > **Developer** > > For hobbyists and proof-of-concept projects. Includes online verification and community support at no cost. > **Starter** > > For SMBs and startups with production workloads. Higher quotas, up to 3 webhook endpoints, and priority processing. > **Business** > > For mid-market teams with compliance needs. SAML SSO, SCIM provisioning, full RBAC and audit logs, up to 10 webhook endpoints, and a 4-hour support SLA. > **Institutional** > > For large enterprises with advanced security needs. Private transparency log, HSM integration, and a 1-hour support SLA. > **Enterprise** > > Custom pricing for governments and Fortune 500. Custom SLA, on-premise deployment options, 24/7 support, and tailored onboarding. ## Core concepts * **Entitlements** — each plan unlocks specific features and quotas (mint limits, verification counts, seats, storage, API rate limits). The billing service enforces these limits at the API layer. * **Usage counters** — available meters are reported for the selected billing cycle. You can monitor your consumption from the console usage dashboard or the [usage API](/api-reference/billing/usage). * **Multi-provider routing** — payments are processed through the optimal gateway for your region. See [provider routing](/billing/provider-routing) for details. ## Metered products Truthlocks meters 16 products organized into four categories. You can see all of them on the [pricing page](https://www.truthlocks.com/pricing) and track your consumption in the console at **Settings > Billing > Usage**. ### Core | Product | Description | Default rate | | :- | :- | :- | | Attestation mints | Attestations created via the API or SDK | \$0.25 per mint | | Verifications | Attestation verification requests | \$0.10 per verification | | Storage | Total file and evidence storage consumed | Included per plan | | Proof bundles | Cryptographic proof bundles generated | Included per plan | | Webhook endpoints | Active webhook endpoint registrations | Included per plan | | Webhook deliveries | Individual webhook delivery attempts | Included per plan | | Seats | Team member seats in your organization | Included per plan | ### MAIP (Machine Identity) | Product | Description | Default rate | | :- | :- | :- | | Agents | Registered machine agents | Per plan tier | | Sessions | Agent sessions created per month | Per plan tier | | Trust score computes | On-demand trust score calculations | Per plan tier | | Compliance checks | Compliance verification requests | Per plan tier | ### AI | Product | Description | Default rate | | :- | :- | :- | | Dataset attestations | Datasets attested for lineage tracking | Per plan tier | | Model attestations | ML models attested for provenance | Per plan tier | ### Anti-Fraud | Product | Description | Default rate | | :- | :- | :- | | Risk signals | Fraud signals ingested or generated | Per plan tier | | Deepfake scans | Deepfake and impersonation scan requests | Per plan tier | | Velocity records | Velocity scoring action records | Per plan tier | > [!NOTE] > > Use the [pricing page](https://www.truthlocks.com/pricing) for published pricing. The projected-invoice API currently prices mints and verifications; other products need their applicable pricing agreement. ## Rate cards Per-use rates for mints and verifications are: | Operation | Rate | | :- | :- | | Attestation mint | \$0.25 per mint | | Verification | \$0.10 per verification | Rates are visible in the console under **Settings > Billing > Usage**. > [!NOTE] > > Rates were reduced by 50% in the March 2026 release. The previous rates were $0.50 per mint and $0.20 per verification. ### Custom rate cards for partners Platform administrators can create custom rate cards with per-operation pricing for partner tenants. Use this to offer negotiated pricing to strategic partners or volume customers without changing your standard plan rates. Each rate card defines unit prices for mints and verifications, and can be assigned to one or more tenants with an effective date. Negotiated rates apply to every billable production operation while the agreement is effective. A resource cap is not a free allowance. Free developer allowances, consumer subscriptions, sandbox activity, and approved no-charge pilots are separate from negotiated business pricing. Volume bands are graduated: if the first 100 operations cost $0.25 each and subsequent operations cost $0.20, 101 operations cost \$25.20. A later band does not reprice earlier operations. Bands must cover the full quantity without gaps or overlaps. A discounted partnership rate card is not a free pilot. An approved pilot has an expiry and usage caps, with no automatic paid conversion. > [!NOTE] > > Accepted usage is now recorded in an immutable, environment-separated ledger with its rate, country, and plan snapshot. Prices are fixed at acceptance by the billing service, not supplied by a caller's backfill timestamp. New pricing does not reprice accepted records. Old aggregate counters are not back-billed. > > Closed UTC months produce invoice drafts automatically. A draft is not payable: issuing it requires staff MFA, an active matching-currency invoice contract, verified billing country, confirmation of the customer's agreement, and explicit tax review. This workflow does not charge saved payment methods or send email. Verified funds received are recorded separately, with duplicate-reference and outstanding-balance checks. > > Free plans, consumer plans, sandbox activity and approved no-charge pilots are excluded from rated business usage. Missing environment or pricing evidence for core operations holds the affected month for review. Automatic settlement currently supports the USD-denominated rate catalog, including its regional discounts; other currencies are held for review. ### Usage projections The console usage page shows recorded consumption and your current rate card. The authenticated projected-invoice API estimates mint and verification costs using the standard rate card; it does not resolve private negotiated rates, tax, free allowances, or an issued invoice. Navigate to **Settings > Billing > Usage** to inspect usage and rates. Read issued invoices separately. ## Entitlement quotas Your plan determines the following quotas: | Quota | Developer | Starter | Business | Institutional | Enterprise | | :- | :- | :- | :- | :- | :- | | Attestation mints | 500/month | Higher | Custom | Custom | Custom | | Monthly verifications | Plan-dependent | Plan-dependent | Plan-dependent | Plan-dependent | Plan-dependent | | Issuers | 1 | Multiple | Custom | Custom | Plan-dependent | | Seats | 1 | Multiple | Custom | Custom | Custom | | Signing keys | 1 | Multiple | Custom | Custom | Plan-dependent | | Webhook endpoints | 1 | 3 | 10 | 25 | 25+ | | Storage | 1 GB | Higher | Custom | Custom | Custom | | API rate limit | 60 req/min | Higher | Custom | Custom | Custom | | SSO & SCIM | — | — | Included | Included | Included | | Private transparency log | — | — | — | Included | Optional | | HSM integration | — | — | — | Included | Optional | | Support SLA | Community | 48-hour email | 4-hour | 1-hour | Custom | ## Add-ons You can attach add-ons to your plan for additional capabilities. Add-ons are billed separately and stack on top of your base plan entitlements. | Add-on | Key | Base price | What it unlocks | | :- | :- | :- | :- | | Extra Seats | `addon_seat` | \$25/seat/mo | +1 team member per unit beyond your plan limit. Supports quantity — set the number of extra seats you need at checkout. | | Priority SLA | `addon_sla_priority` | \$199/mo | Upgrade to 4-hour response time SLA | | Private Log | `addon_private_log` | \$499/mo | Dedicated transparency log namespace | | Compliance Pack | `addon_compliance` | \$299/mo | SOC 2, GDPR, and HIPAA compliance reporting | | White-Label | `addon_whitelabel` | \$199/mo | Remove Truthlocks branding from verification pages | | Rate Limit Boost | `addon_ratelimit` | \$149/mo | 10x default API rate limits | | Extended Retention | `addon_retention` | \$99/mo | 10-year audit log retention (default is 2 years) | Manage add-ons in the console at **Settings > Billing > Add-ons**. The add-ons marketplace shows all available add-ons with your regional price, a description, and a one-click attach button. Add-ons that support quantity (like Extra Seats) let you choose the number of units before purchasing. You can also check your active add-ons and resolved entitlements via the API: ```bash theme={null} curl https://api.truthlocks.com/v1/billing/entitlements \ -H "X-API-Key: tl_live_..." ``` ```json theme={null} { "plan_key": "plan_starter", "features": { "online_verification": true, "offline_bundles": true, "custom_metadata": true, "sso_scim": false }, "quotas": { "attestations.mint": 5000, "seats": 4, "api_rate_limit": 1200, "storage_bytes": 10737418240, "webhook_endpoints": 3 } } ``` > [!NOTE] > > Pricing for add-ons adjusts automatically based on your region and payment provider. Free add-ons (like Extra Seats on Enterprise plans) activate immediately without a checkout step. ### Regional add-on pricing Add-on prices are adjusted automatically based on your organization's country. The billing system groups countries into pricing tiers and applies a multiplier to the base price. | Region | Multiplier | Countries | | :- | :- | :- | | Tier 1 | 1.0x (full price) | US, GB, DE, FR, CA, AU, NL, CH, JP, SG, IE, IT, ES, SE, NO, DK, FI, NZ | | LATAM | 0.7x | BR, MX, AR, CO, CL, PE | | MENA | 0.8x | AE, SA, EG, IL, TR, ZA | | Southeast Asia | 0.6x | ID, TH, VN, PH, MY | | Africa | 0.5x | NG, KE, GH, TZ, UG, RW | | South Asia | 0.5x | IN, PK, BD, LK | For example, the Compliance Pack add-on at a base price of $299/month costs $149.50/month for a tenant in Nigeria (0.5x multiplier). Regional multipliers also apply to per-use rates for mints and verifications. A tenant in India (0.5x) pays $0.125 per mint and $0.05 per verification instead of the standard $0.25 and $0.10 rates. You can check your effective rates with the [rates endpoint](/api-reference/billing/rates). > [!TIP] > > Use the country selector on the add-ons page to preview pricing for a specific region. The selector does not change your billing country — it only adjusts the displayed prices. ## Purchase order billing Enterprise tenants can pay via purchase order as an alternative to credit card or regional payment providers. **1. Submit a purchase order** Navigate to **Settings > Billing** and select the purchase order option. Upload your PO document (PDF), enter the PO number, amount, and expiry date. **2. Review and activation** The Truthlocks billing team reviews your PO. Once approved, your account is activated and invoices are issued against the PO balance. **3. Track PO status** View PO status, remaining balance, and associated invoices from the billing settings page. > [!NOTE] > > Purchase order billing is available on the Enterprise plan. Contact your > account manager if you need PO-based payment on a different plan. ## Accounting export Enterprise tenants can export their invoice history as CSV or JSON for accounting and reconciliation. Exports include invoice number, status, issue and due dates, amounts, tax, currency, and PO references. If no date range is provided, the export defaults to the last 30 days. ```bash theme={null} curl "https://api.truthlocks.com/v1/billing/exports/accounting?format=csv&from=2026-01-01&to=2026-06-30" \ -H "X-API-Key: tl_live_..." ``` | Parameter | Type | Description | | :- | :- | :- | | `format` | string | Export format: `csv` or `json`. Defaults to `csv`. | | `from` | string | Start date (`YYYY-MM-DD`, e.g. `2026-01-01`). Defaults to 30 days ago. | | `to` | string | End date (`YYYY-MM-DD`, e.g. `2026-06-30`). Defaults to today. | The response streams the file directly. For CSV exports, the `Content-Type` is `text/csv` with a `Content-Disposition` header for download. You can also export invoices from the console at **Settings > Billing > Invoices > Export**. > [!NOTE] > > Accounting export is available on the Enterprise plan. The export includes all > invoices within the specified date range, including paid, open, and void > invoices. ## Payment failures and grace periods If a payment fails, Truthlocks follows a graduated access workflow so you have time to resolve the issue before losing access. You can check your current billing status at any time via the [`GET /v1/billing/status`](/api-reference/billing/status) endpoint. ```bash theme={null} curl https://api.truthlocks.com/v1/billing/status \ -H "X-API-Key: tl_live_..." ``` ```json theme={null} { "status": "ACTIVE", "feature_mode": "NORMAL", "grace_until": null, "banner": null } ``` The billing status progresses through three stages when a payment fails: | Stage | `feature_mode` | Default grace window | What happens | | :- | :- | :- | :- | | **Degraded** | `DEGRADED` | 7 days | Payment failed. A grace period begins and a banner appears in the console. All features remain available while you update your payment method. | | **Restricted** | `RESTRICTED` | 14 days | Grace period is running out. Write operations (minting, key creation) are disabled. Read operations and verification continue to work. | | **Suspended** | `SUSPENDED` | — | Grace period expired. All API access is disabled until payment is resolved. | The `grace_until` field shows the ISO 8601 timestamp when the current grace period ends. Resolve the payment before this date to restore full access automatically. The grace windows above apply to the Standard contract mode — Enterprise and Government modes use longer windows. See [contract modes](#contract-modes) for details. ### Contract modes How the dunning lifecycle behaves depends on the tenant's contract mode. By default, all tenants use the Standard mode, but platform administrators can switch a tenant to a different mode from the billing operations console. | Mode | Retries | Grace period | When to use | | :- | :- | :- | :- | | **Standard (Auto)** | Automatic retries at T+24h, T+48h, T+72h | 7 days (Degraded) then 14 days (Restricted) before suspension | Self-serve tenants paying by credit card or regional payment provider | | **Enterprise (Manual)** | No automatic retries — billing admin intervenes | 21 days (Degraded) then 28 days (Restricted) — standard windows plus 14 extra days | Enterprise accounts paying by wire transfer or purchase order | | **Government (No Retry)** | No automatic retries | Fixed 90-day grace period; no automatic suspension | Government procurement workflows where payment timelines are outside your control | The Standard mode sends up to three payment reminders at 24-hour, 48-hour, and 72-hour intervals after each stage transition. Enterprise and Government modes skip automatic retries entirely — a billing administrator must resolve the payment manually. > [!NOTE] > > Contract mode changes are audit-logged and require a reason. Contact support to request a contract-mode change. When using the [estimate endpoint](/api-reference/billing/estimate), you can pass `contract_mode` as `ENTERPRISE_CONTRACT` or `GOVERNMENT_PROCUREMENT` to get a plan recommendation that accounts for the contract type. Omitting this field defaults to `STANDARD_SELF_SERVE`. > [!TIP] > > Check `feature_mode` in your integration to surface upgrade or payment prompts > to your users before access is restricted. A `banner` message is included when > action is needed. See the [billing status API reference](/api-reference/billing/status) for full response details and usage examples. ## Managing billing All billing settings are managed in the console at **Settings > Billing**. From there you can: * View your current plan and entitlements * Monitor usage counters and rate consumption * Upgrade or downgrade your plan * View and download invoices * Export invoices for accounting (Enterprise) * Submit purchase orders (for enterprise accounts) * Attach or detach add-ons ## Checking limits via the API Before performing a billable operation, you can check whether your current quota allows it: ```bash theme={null} curl -X POST https://api.truthlocks.com/v1/billing/limits/check \ -H "X-API-Key: tl_live_..." \ -H "Content-Type: application/json" \ -d '{"metric": "attestations.mint", "amount": 1}' ``` The response indicates whether the operation is allowed under your current plan: ```json theme={null} { "allowed": true, "used": 158, "limit": 500, "delta": 1 } ``` ### Grace period extensions in limit checks If your usage exceeds your plan limit but a platform administrator has granted a grace period for that metric, the response includes a `grace` object with the temporary allowance details: ```json theme={null} { "allowed": true, "used": 510, "limit": 500, "grace": { "active": true, "amount": 100, "expires_at": "2026-04-15T12:00:00Z" }, "delta": 1 } ``` ## Related > **[Subscription management](/guides/subscription-management)** > > Subscribe, upgrade, attach add-ons, and cancel via the API. > **[Provider routing](/billing/provider-routing)** > > How payments are routed by region. > **[List plans](/api-reference/billing/plans)** > > Fetch available plan tiers with pricing and features. > **[Get rates](/api-reference/billing/rates)** > > Your effective per-use rates with regional adjustments. > **[Estimate costs](/api-reference/billing/estimate)** > > Get a plan recommendation based on expected usage. > **[Billing status API](/api-reference/billing/status)** > > Check your billing health, feature mode, and grace period status. > **[Billing API reference](/api-reference/billing/config)** > > Configuration, entitlements, checkout, subscription, and invoice endpoints. > **[Usage API](/api-reference/billing/usage)** > > Check your current billing cycle usage counters. # Billing country and payment providers Source: https://docs.truthlocks.com/billing/provider-routing Country verification, regional pricing, and choosing an available payment provider. Your billing country is selected when registering a business workspace or personal account. Paid-plan activation, paid add-ons and payable invoice issuance require staff approval of evidence supporting that country. ## Verify your country Open **Settings > Billing > Verify billing country** in Console or Verify. Upload a PDF, PNG or JPEG of up to 5 MB showing your residence or your organization's registration/address. Platform staff review the evidence and record their decision. Nationality alone does not necessarily establish residence. A pending country-change review prevents new paid billing until resolved. Changing a recorded country invalidates its previous approval; changing it back does not restore that approval. A rejected change leaves any still-valid approval for the unchanged original country intact. ## Prices and provider choices The authenticated billing configuration and plan catalog use the saved account country. URL country parameters and network location do not change that account's billing country. Public, unauthenticated catalog estimates may accept a country for comparison; these estimates do not verify eligibility. The current regional catalog applies existing country-group multipliers: full price, Latin America 70%, Middle East/North Africa 80%, Southeast Asia 60%, and the configured Africa and South Asia groups 50%. Country coverage follows the service's country mapping; these are not blanket discounts for every country on a continent. Individually agreed contracts require their own terms review. Use `visible_providers` from [billing configuration](/api-reference/billing/config) to offer Stripe or Flutterwave, and `effective_provider` as the default. Configured African routes can offer both. An empty provider list means no provider is available for the recorded country. Paystack is not part of this implementation. Catalog and current hosted checkout amounts are in **USD**. Regional discounts do not imply local-currency collection or that every bank/mobile-money method is enabled. The provider displays the payment methods actually available for the currency and merchant account. > [!WARNING] > > Flutterwave monthly subscriptions require configured recurring payment plans. Checkout refuses to substitute a one-time charge when a recurring plan is missing. A listed provider or a checkout link does not prove that payment succeeded. ## Existing subscriptions Payment management follows the provider recorded on the subscription. Choosing a different option does not silently transfer an existing subscription or its payment methods. Manage an existing paid subscription before starting a replacement checkout to avoid duplicate subscriptions. Stripe supports the configured payment-method portal. Flutterwave does not provide a matching self-service portal in Truthlocks; use billing support for existing payment arrangements. ## API handling A checkout blocked by country review returns HTTP `409` with code `BILLING_COUNTRY_REVIEW_REQUIRED`. Direct the account holder to the signed-in country-review page. Do not retry with another country parameter or provider to bypass approval. See [checkout](/api-reference/billing/checkout), [plans](/api-reference/billing/plans), and [payment management](/api-reference/billing/portal). # Product Changelog Source: https://docs.truthlocks.com/changelog New updates, feature releases, and improvements to Truthlocks > [!NOTE] > > Historical entries describe changes announced at the time, not the current availability of every feature or SDK method. The current operation reference and implementation limitations take precedence. Earlier infrastructure, pricing, and release-readiness claims have been revised where they conflicted with the recovery deployment. > Earlier claims of a released Python StreamingGateway, a working multi-backend standalone gateway, and verified public Docker images were incorrect. See the [current integration limitations](/guides/maip-integrations#event-streaming). **Week of June 30, 2026** Deployment reliability fix ensures platform updates ship without delay ## Deployment reliability fix A fix to the build pipeline ensures that all platform updates — including the billing and audit fixes from recent weeks — are deployed to production without delay. ### Bug fixes * **Platform updates now deploy reliably:** A build pipeline issue was causing Docker layer caching to prevent new code changes from being included in deployments, which could delay platform updates from reaching production. Deployments now always include the latest changes, ensuring that bug fixes and improvements ship on schedule. **Week of June 23, 2026** Billing tenant isolation and trust registry audit query reliability ## Billing tenant isolation and audit query reliability Two fixes improve data isolation on billing endpoints and restore audit queries that failed when event outcome or detail fields were empty. ### Bug fixes * **Billing endpoints now enforce tenant isolation at the database level:** Internal [billing](/billing/overview) endpoints — including [usage tracking](/api-reference/billing/usage) and [subscription management](/guides/subscription-management) — were not passing your authenticated session context to the database layer, which meant [row-level security](/security/rls) policies could not enforce tenant boundaries on those queries. Billing requests now carry the correct authentication context, ensuring your billing data is isolated at the database level in addition to the application layer. * **Trust registry audit queries no longer fail on empty outcome or detail fields:** A follow-up to [last week's fix](/changelog#trust-registry-audit-query-fix) — [audit log](/security/audit) queries that included events with empty outcome or detail fields were still returning errors because the trust registry could not read NULL values in those columns. If you were seeing failed audit queries for events that had no recorded outcome or detail, those now return results as expected. **Week of June 16, 2026** Trust registry audit query fix for nullable columns ## Trust registry audit query fix A database compatibility fix restores audit event queries in the trust registry when actor or action fields are empty. ### Bug fixes * **Trust registry audit queries no longer fail on empty fields:** [Audit log](/security/audit) queries that included events with empty actor or action fields were returning errors because the trust registry could not read NULL values from the database. If you were seeing failed audit queries — particularly for system-generated events that have no associated actor — those now return results as expected. **Week of June 9, 2026** Gateway routing and cross-origin fixes for attestation and machine identity APIs ## Gateway routing and CORS fixes Fixes to the API gateway restore correct routing for attestation and transparency log endpoints, and enable cross-origin requests with API key authentication for browser-based SDK integrations. ### Bug fixes * **Attestation and transparency log API routing fixed:** The [attestation](/api-reference/attestations/mint) and transparency log endpoints were returning unexpected responses because the gateway was stripping the URL path prefix before forwarding requests. If you were calling attestation or transparency log API routes and receiving errors, those should now be resolved. * **Cross-origin API key authentication for attestation and machine identity endpoints:** Browser-based applications calling [attestation](/api-reference/attestations/mint) or [machine identity](/api-reference/machine-identity/agents/register) endpoints with the `X-Api-Key` header could receive CORS errors because the header was not included in the gateway's allowed CORS headers. If you use the [JavaScript SDK](/sdk/js) or make direct browser-based API calls to these endpoints, cross-origin requests with API key authentication now work as expected. **Week of June 2, 2026** Audit log reliability fix for console pages ## Audit log reliability fix A database compatibility fix restores audit log functionality across all console pages. ### Bug fixes * **Audit log pages no longer return errors:** The [audit log](/security/audit) pages in the [console](https://console.truthlocks.com) — including tenant audit, platform audit, and admin audit views — were returning 500 errors when loading event data. This was caused by a database type incompatibility that prevented audit events containing IP addresses and outcome fields from being read correctly. All three audit views now load and display events as expected. **Week of May 26, 2026** Billing and trust registry migration reliability improvements ## Billing and trust registry migration reliability Database migration handling has been hardened across the billing service and trust registry, reducing the risk of service disruptions during platform deployments. ### Bug fixes * **Billing service deployment reliability improved:** The [billing service](/billing/overview) could fail to start if a previous deployment left the database in a partially migrated state. The migration runner now automatically recovers from dirty or incomplete migrations, so billing operations — including [subscription management](/guides/subscription-management), [usage tracking](/api-reference/billing/usage), and [invoice generation](/api-reference/billing/invoices) — remain available through deployments without manual intervention. * **Trust registry migration stability:** The [trust registry](/trust/security) could fail during redeployments if a database index already existed from a prior run. Index creation is now idempotent, preventing deployment failures that could temporarily affect attestation verification and issuer lookups. **Week of May 19, 2026** New verification landing page, expanded API route coverage, and authentication reliability fix ## Verification landing page, expanded API routes, and auth fix A new public verification page on the website, faster homepage performance, expanded API gateway route coverage, and a fix for API key authentication. ### New features * **Verification landing page:** A new [/verify](https://www.truthlocks.com/verify) page on the website explains how Truthlocks cryptographic verification works and links directly to the [verification portal](https://verify.truthlocks.com). Use it as a shareable entry point for anyone who needs to verify an attestation or receipt. ### Updates * **Faster homepage loading:** Below-the-fold sections on the [homepage](https://www.truthlocks.com) are now lazy-loaded, reducing initial page load time. Preconnect hints for analytics services further improve First Contentful Paint and Largest Contentful Paint scores. * **Improved search engine discoverability:** The [website](https://www.truthlocks.com) now includes hreflang locale signals, richer structured data (Organization schema, feature lists, and aggregate offers), and an expanded sitemap. Thirteen redirects have been added for legacy URL paths, so old bookmarks and external links now resolve correctly instead of returning 404s. * **AI bot guidance with llms.txt:** A new [llms.txt](https://www.truthlocks.com/llms.txt) file provides structured guidance for AI crawlers and large language models, helping them understand Truthlocks content more accurately. * **Expanded API gateway route coverage:** Nine additional route groups — including settings, privacy, invitations, messages, environments, attestation packs, issuer applications, and assets — are now properly routed through the production API gateway. If you previously received unexpected errors when calling these endpoints, those should now be resolved. ### Bug fixes * **API key authentication restored:** A database migration issue could cause all [API key](/api-reference/api-keys/create) authenticated requests to fail with an internal error. The authentication layer now handles both the old and new database schema gracefully, so existing API keys continue to work without interruption. * **Audit log API routing fixed:** The [audit log](/api-reference/audit/query) endpoints were returning incorrect responses because the gateway was stripping the URL path prefix before forwarding requests. Audit queries and exports now route to the correct backend service. **Week of May 12, 2026** Interactive API playground for Machine Identity endpoints, observability accuracy improvements, and homepage layout fixes ## MAIP API playground, observability accuracy, and homepage fixes All 29 Machine Identity (MAIP) API endpoints now support the interactive API playground, health probe accuracy has been improved across monitored services, and several homepage layout issues have been resolved. ### Updates * **Interactive API playground for MAIP endpoints:** All 29 [Machine Identity API endpoints](/api-reference/machine-identity/agents/register) — including [agents](/api-reference/machine-identity/agents/register), [sessions](/api-reference/machine-identity/sessions/create), [trust scores](/api-reference/machine-identity/trust-scores/compute), [truth claims](/api-reference/machine-identity/truth-claims/create), [compliance checks](/api-reference/machine-identity/compliance/create-check), [datasets](/api-reference/machine-identity/datasets/attest), [models](/api-reference/machine-identity/models/attest), [orchestrations](/api-reference/machine-identity/orchestrations/execute), and [workflows](/api-reference/machine-identity/workflows/create) — now support the interactive playground in the API reference. You can send live requests directly from the docs against Sandbox or Production without leaving the page. * **More accurate health monitoring:** Health probes used by the [observability dashboard](/guides/observability) and [status page](https://status.truthlocks.com) now use the correct URL scheme and handle request errors gracefully. If a monitored service was previously showing an incorrect health status due to a probe misconfiguration, that should now be resolved. ### Bug fixes * **Homepage layout and animation fixed:** The [homepage](https://www.truthlocks.com) navigation buttons, live demo grid alignment, and CLI typewriter animation were not rendering correctly. All three are now displaying and animating as expected. **Week of May 5, 2026** Content Security Policy and CSRF fixes restore full functionality across all web applications ## Content Security Policy and CSRF fixes Two follow-up fixes to the [browser security hardening](/changelog#stronger-browser-security-across-all-web-apps) shipped in Week of April 14 restore full functionality across all Truthlocks web applications. ### Bug fixes * **Web applications no longer stuck on loading screens:** All six Truthlocks web apps — [console](https://console.truthlocks.com), [verification portal](https://verify.truthlocks.com), [status page](https://status.truthlocks.com), [Trust Explorer](https://transparency.truthlocks.com), [website](https://www.truthlocks.com), and [docs](https://docs.truthlocks.com) — could get stuck on a loading spinner because the nonce-based Content Security Policy introduced in Week of April 14 was blocking page scripts from running. Nonces are now correctly wired from the server middleware into each page, so scripts load as expected. * **Console and verification portal form submissions no longer blocked:** State-changing requests (such as revoking an attestation or updating settings) in the [console](https://console.truthlocks.com) and [verification portal](https://verify.truthlocks.com) were returning 403 errors because the CSRF protection introduced in Week of April 14 required a token that the frontend was not sending. CSRF tokens are now included automatically on all relevant requests, so form submissions and actions work without errors. **Week of April 28, 2026** Expanded SCIM filter attribute support for identity provider compatibility ## Expanded SCIM filter attribute support The [SCIM provisioning endpoint](/security/scim) now supports filtering on additional user attributes, improving compatibility with more identity providers out of the box. ### Updates * **SCIM filtering on displayName and externalId:** The [SCIM provisioning endpoint](/security/scim#filtering) now supports filtering users by `displayName` and `externalId` in addition to `userName`. Identity providers like Azure AD that send `displayName`-based filter queries during sync now work correctly without returning errors. See the [supported filter operators](/security/scim#supported-operators) and [common IdP filter patterns](/security/scim#common-idp-filter-patterns) for details. **Week of April 21, 2026** Database-level tenant isolation and additional security hardening across console and blog ## Database-level tenant isolation and security hardening All user-facing API operations now enforce tenant isolation at the database level, and additional security fixes protect the console login flow and blog content. ### Updates * **Database-level tenant isolation:** All consumer and admin API operations — including [attestation management](/api-reference/attestations/mint), [API key management](/api-reference/api-keys/list), [portfolio access](/api-reference/consumer/portfolio), [privacy exports](/api-reference/consumer/privacy/export), and [account settings](/guides/account-security) — now enforce tenant isolation at the PostgreSQL layer using row-level security policies, in addition to existing application-level checks. This defense-in-depth improvement ensures that even in the event of an application-level bug, one tenant's data cannot be accessed by another. No action is required on your part. * **Console login security hardened:** The [console](https://console.truthlocks.com) login flow no longer returns authentication tokens in the response body. Tokens are now set exclusively as HTTP-only cookies, reducing your exposure if a cross-site scripting vulnerability were ever present on the page. * **Blog content sanitized against XSS:** Blog posts served on the Truthlocks website are now sanitized before rendering, preventing any malicious content in API-fetched posts from executing in your browser. * **Internal service schema no longer exposed:** The signing service previously allowed unauthenticated clients to query its internal API schema via gRPC reflection. Reflection is now disabled in production, reducing the information available to potential attackers. **Week of April 14, 2026** SCIM provisioning improvements, deeper security hardening, and console reliability fixes ## SCIM provisioning, security hardening, and console reliability Expanded SCIM filter support for identity providers, stronger browser security across all web applications, and fixes for console page loading and observability accuracy. ### Updates * **Expanded SCIM filter support:** The [SCIM provisioning endpoint](/security/scim) now supports additional filter operators — including `and`, `or`, `ne`, `co`, `sw`, and `ew` — in addition to the existing `eq` filter. If your identity provider (Okta, Azure AD, etc.) sends complex filter queries during user and group sync, those queries are now handled correctly instead of returning errors. * **Stronger browser security across all web apps:** All Truthlocks web applications — including the [console](https://console.truthlocks.com), [verification portal](https://verify.truthlocks.com), [status page](https://status.truthlocks.com), [Trust Explorer](https://transparency.truthlocks.com), and [docs](https://docs.truthlocks.com) — now use nonce-based Content Security Policies instead of static inline rules, and the console and verification portal enforce CSRF protection on all state-changing requests. These changes reduce your exposure to cross-site scripting and request forgery attacks. * **API error responses no longer leak internal details:** All API services now return a generic error message for 500-level responses instead of exposing internal error details. This applies to the [attestation](/api-reference/attestations/mint), [verification](/api-reference/verify), [machine identity](/api-reference/machine-identity/agents/register), and trust registry services. Internal errors are still logged server-side for debugging. * **Improved API stability under unexpected failures:** All nine backend services now include panic recovery middleware, which prevents unexpected internal errors from dropping your connection. If a service encounters an unhandled error, you now receive a proper error response instead of a closed connection. This complements the [gateway resilience improvements](/ops/health#gateway-resilience) shipped previously. * **Observability dashboard shows real latency data:** The [observability dashboard](/guides/observability) previously displayed a hardcoded 500ms p99 latency value. It now computes real p99 latency from actual health check measurements, giving you accurate performance data for all monitored services. ### Bug fixes * **Console machine identity and receipts pages load correctly:** Ten console pages — including the machine identity activity feed, trust distribution, trust policy, low-trust agents, and several receipts management views — were failing to load due to missing API routes. All affected pages now load and display data as expected. * **Anti-fraud dashboard data loading fixed:** The anti-fraud page in the [console](https://console.truthlocks.com) was showing a "Failed to load risk data" error because it was calling incorrect API routes. The page now fetches data from the correct endpoints and displays risk metrics properly. * **Homepage live demo and CLI animation fixed:** The [live demo](https://www.truthlocks.com) section on the homepage had layout alignment issues on desktop and the CLI typewriter animation was not playing. Both are now rendering and animating correctly. **Week of April 7, 2026** Status page accuracy and security hardening across all web applications ## Status page accuracy and security hardening The [status page](https://status.truthlocks.com) now reflects real service health, and all Truthlocks web applications enforce stricter cross-origin and browser security policies. ### Updates * **Stricter cross-origin and browser security policies:** All Truthlocks web applications — including the [console](https://console.truthlocks.com), [verification portal](https://verify.truthlocks.com), [status page](https://status.truthlocks.com), and [Trust Explorer](https://transparency.truthlocks.com) — now enforce a strict CORS origin whitelist instead of reflecting any origin. Additional security headers have been applied across all services, including frame protection, content-type sniffing prevention, referrer policy, and transport security. These changes reduce your exposure to cross-site attacks when using any Truthlocks app. * **Production API route coverage expanded:** Several API route groups — including [billing](/api-reference/billing/status), [consumer](/api-reference/consumer/signup), [webhooks](/api-reference/webhooks/create-endpoint), [receipts](/api-reference/receipts/mint), and [machine identity](/api-reference/machine-identity/agents/register) — are now fully routed in the production gateway, closing gaps where certain endpoints could return unexpected errors. If you previously encountered routing issues with any of these endpoints in production, those should now be resolved. ### Bug fixes * **Status page uptime bars now reflect actual service health:** The [status page](https://status.truthlocks.com) uptime bars previously showed 100% uptime regardless of actual service status. Uptime bars now reflect known incidents and display amber or red when a service is currently degraded or down. A new [incident history](https://status.truthlocks.com/history) section also shows past platform events so you can see what happened and when. **Week of August 19, 2028** Dynamic social sharing previews for the Truthlocks website ## Dynamic social sharing previews Links to [truthlocks.com](https://www.truthlocks.com) now render richer, on-brand preview cards when shared on social platforms. ### Updates * **Dynamic Open Graph and Twitter card images:** When you share a link to [truthlocks.com](https://www.truthlocks.com) on social media, Slack, or any platform that supports link previews, the preview card now displays a dynamically generated image that matches the current homepage branding — including the "The Trust Platform for Machine & Digital Identity" headline and compliance badges. Previously, shared links used a static image that could fall out of date with the live site. No action needed on your part — this applies automatically to all shared links going forward. **Week of August 12, 2028** Interactive live demo, CLI animation, and website navigation improvements ## Interactive live demo and website improvements The [homepage](https://www.truthlocks.com) now features an interactive live demo, an animated CLI section, expanded navigation, and theme fixes across several sections. ### New features * **Interactive live demo on homepage:** A new [live demo section](https://www.truthlocks.com) on the homepage showcases animated walkthroughs for verification, attestation, machine identity, and receipt anchoring — auto-cycling through each flow so you can see the platform in action without leaving the page. For a hands-on version, visit the [full demo page](https://www.truthlocks.com/demo). ### Updates * **Animated CLI hero:** The CLI section on the [homepage](https://www.truthlocks.com) now features a typewriter animation with a blinking cursor that triggers as you scroll into view and replays automatically — giving a better sense of how the [CLI](/guides/protect-cli) works in practice. * **Enterprise-first homepage layout:** Homepage sections have been reordered to lead with platform capabilities, how it works, and impact — placing enterprise content front and center. The creator-focused section now appears later on the page. * **Expanded header and footer navigation:** The site header now includes links to [Compliance Engine](https://www.truthlocks.com/product/compliance-autopilot), [Enterprise Platform](https://www.truthlocks.com/enterprise), [Healthcare](https://www.truthlocks.com/industries/healthcare), and [Code Authorship](https://www.truthlocks.com/use-cases/code-authorship). The footer has been updated with additional product, solution, and resource links. The Support Center link now correctly points to `/help`. ### Bug fixes * **Homepage dark mode rendering fixed:** Several homepage sections — including the creator showcase and "how it works" cards — were not rendering correctly in light mode. Both light and dark themes now display as expected across all homepage sections. * **Footer label corrected:** The "Enterprise" link in the footer Solutions column was mislabeled — it actually linked to the supply chain page. The label now correctly reads "Supply Chain." **Week of August 5, 2028** Website rebrand and infrastructure monitoring improvements ## Website rebrand and infrastructure monitoring The [Truthlocks homepage](https://www.truthlocks.com) now reflects the platform's expanded scope, and new infrastructure monitoring strengthens service reliability. ### Updates * **Homepage rebrand:** The [homepage](https://www.truthlocks.com) hero now positions Truthlocks as "The Trust Platform for Machine & Digital Identity" with a "Full-Stack Trust Ecosystem" badge, reflecting the platform's growth beyond attestations into [machine identity (MAIP)](/guides/machine-identity), [risk detection](/guides/risk-signals), and [compliance tooling](/guides/compliance-exports). No functional changes — this is a messaging update to better describe what the platform does today. * **Infrastructure monitoring for service reliability:** All backend services now have automated health monitoring with alerts for high CPU usage, elevated memory consumption, and service availability drops. These controls align with SOC 2 monitoring requirements and help ensure faster incident response if a service degrades. You can check current service status anytime on the [status page](https://status.truthlocks.com). **Week of July 29, 2028** API resilience hardening and extended data backup retention ## API resilience and data protection improvements Platform-wide hardening improves API reliability under adverse conditions, and an extended backup retention window strengthens data protection for compliance. ### Updates * **Extended backup retention for SOC 2 alignment:** Production database backups are now retained for 30 days, up from 7 days. This provides a longer point-in-time recovery window and aligns with SOC 2 audit expectations for data backup controls. No action is required on your part — your data is automatically covered by the extended retention policy. See [trust & compliance](/trust/compliance) for more on how Truthlocks aligns with SOC 2. * **API gateway resilience improvements:** The [API gateway](/api-reference/attestations/mint) now includes automatic panic recovery, which prevents unexpected internal errors from dropping your connection. Previously, certain edge-case failures could cause the gateway to reset in-flight connections. Requests that encounter an internal error now return a proper error response instead of a dropped connection. During deployments, the gateway and signing service also drain in-flight requests over a 15-second window instead of terminating them immediately. See [gateway resilience](/ops/health#gateway-resilience) for details. * **DoS protection across all services:** All API services now enforce HTTP server timeouts that protect against slowloris-style denial-of-service attacks. This improves availability under sustained low-bandwidth connection attempts and helps ensure consistent response times for legitimate API traffic. See [connection timeout protection](/security/abuse-hardening#connection-timeout-protection) for more details. **Week of July 22, 2028** MAIP Policies API, route namespace change, compliance wording accuracy, and observability improvements ## MAIP Policies API and compliance accuracy A new set of API endpoints lets you define and evaluate runtime enforcement policies for machine agents. A route namespace change affects existing MAIP policy integrations. Compliance language on the website has been corrected for accuracy, and observability coverage has been expanded. ### New features * **MAIP Policies API:** Three new endpoints — [List](/api-reference/machine-identity/policies/list), [Create](/api-reference/machine-identity/policies/create), and [Evaluate](/api-reference/machine-identity/policies/evaluate) — let you define runtime enforcement rules for machine agents. Policies can restrict agent actions based on trust scores, scopes, delegation depth, and agent type. Use the evaluate endpoint as a runtime checkpoint before agents perform sensitive operations. See the [MAIP Policies API reference](/api-reference/machine-identity/policies/create) for the full rule schema. ### Updates * **MAIP policy route namespace change:** MAIP policy endpoints have moved from `/v1/policies` to `/v1/maip/policies` to avoid conflicts with [RBAC issuance policies](/api-reference/policies/create). If you have the previous path hardcoded, update it to `/v1/maip/policies`. The previous path no longer routes to machine identity policies. * **Compliance language corrected:** SOC 2 and ISO 27001 compliance status on the [website](https://www.truthlocks.com) now reads "Aligned" instead of "Ready" or "Certified," reflecting that Truthlocks follows these frameworks without holding a formal certification. GDPR and CCPA remain listed as "Compliant" since they are law-based and do not require third-party certification. * **Expanded observability coverage:** The attestation and audit services now include observability middleware, closing monitoring gaps and improving the accuracy of service health data on the [observability dashboard](/guides/observability) and [status page](https://status.truthlocks.com). **Week of July 15, 2028** Cross-tenant security fix, zero-downtime deployments, and service reliability improvements ## Security hardening, zero-downtime deployments, and reliability fixes A critical tenant isolation fix, smoother deployments with graceful shutdown across API services, and configuration corrections that improve reliability for audit logs, verification, and email notifications. ### Updates * **Zero-downtime deployments:** The [API gateway](/api-reference/attestations/mint) and [signing service](/api-reference/receipts/signing-policy) now drain in-flight requests over a 15-second window during deployments instead of dropping them. If you previously experienced occasional request failures during platform maintenance windows, those should no longer occur. * **Attestation worker stability:** A background worker in the [attestation service](/api-reference/attestations/mint) that handles retention tasks could previously continue running after a shutdown, potentially causing stale state. It now terminates cleanly during restarts. ### Bug fixes * **Tenant isolation hardened:** A security fix ensures that tenant identity is always resolved from your authenticated session rather than request headers, preventing any possibility of cross-tenant data access. This is a defense-in-depth improvement — no action is required on your part. * **Audit log connectivity restored:** The [audit service](/api-reference/audit/query) was missing a required connection to the trust registry in production, which could cause audit log queries to fall back to an incorrect default. Audit queries now route to the correct backend reliably. * **Verification service configuration hardened:** The [verification service](/api-reference/verify) now receives its attestation service connection explicitly in both production and sandbox, eliminating reliance on a fallback default and improving verification reliability. * **Email reply-to address configured:** Platform notification emails — including [incident alerts](/security/email-delivery) and system notifications — now include the correct reply-to address, so replies reach the right destination. **Week of July 8, 2028** API gateway reliability fix for signing and machine identity routes ## API gateway reliability fix A configuration fix ensures the API gateway correctly routes requests to the signing and [machine identity](/guides/machine-identity) services, preventing potential downtime on the next infrastructure deployment. ### Bug fixes * **Signing and machine identity gateway routes restored:** The [API gateway](/api-reference/attestations/mint) was missing two required service URLs — one for the [signing service](/api-reference/receipts/signing-policy) and one for the [machine identity service](/guides/machine-identity). Without these, the gateway would fail to start on the next infrastructure deployment, which could temporarily block signing operations and all [MAIP API endpoints](/api-reference/machine-identity/agents/register). Both URLs are now configured in production and sandbox environments. * **Console deployment pipeline unblocked:** A missing dependency in the console's lockfile was causing Docker builds to fail, which blocked new console deployments. The lockfile has been corrected and console deploys are proceeding normally. **Week of June 24, 2028** Billing service security hardening ## Billing service security hardening A defense-in-depth fix ensures the billing service rejects unauthenticated internal requests in production. ### Bug fixes * **Billing internal authentication hardened:** The billing service could previously fall back to a default development key when the production service key was not configured, potentially allowing unauthenticated internal requests. The service now returns a `503` error if the production key is missing, ensuring that all internal service-to-service calls are properly authenticated. This complements the [billing worker reliability fix](/changelog#billing-service-reliability-improvement) shipped last week and further strengthens the security of billing operations like [subscription management](/guides/subscription-management) and [usage tracking](/billing/overview). **Week of June 17, 2028** Billing service reliability improvement ## Billing service reliability improvement A stability fix for the billing service ensures background workers shut down cleanly during deployments. ### Bug fixes * **Billing background workers now shut down gracefully:** The billing service's background workers — responsible for processing [dunning](/guides/subscription-management) retries and overage calculations — could previously continue running after a deployment restart, which in rare cases led to duplicate processing or stale state. These workers now terminate cleanly during service restarts, improving the reliability of automated billing operations. **Week of June 3, 2028** Complete metered product reference and expanded usage tracking ## Metered product reference and usage tracking You can now see exactly what Truthlocks meters and how each product is tracked — across Core, MAIP, AI, and Anti-Fraud categories. ### Updates * **Complete metered product reference:** The [billing overview](/billing/overview) now documents all 16 metered products organized into four categories — Core (mints, verifications, storage, proof bundles, webhooks, seats), MAIP (agents, sessions, trust score computes, compliance checks), AI (dataset attestations, model attestations), and Anti-Fraud (risk signals, deepfake scans, velocity records). Each product includes a description and default rate, so you know what counts toward your usage before you start building. * **Usage API returns all 16 metrics:** The [usage endpoint](/api-reference/billing/usage) now returns up to 16 counters organized by product group. Each metric includes your current consumption, plan limit, billing period, and unit of measurement — making it straightforward to monitor usage programmatically across all platform services. * **Projected monthly spend in the console:** The usage dashboard at **Settings > Billing > Usage** now shows a projected monthly cost based on your current consumption rate and effective per-unit rates. Use it to forecast spending before the billing cycle closes. **Week of May 27, 2028** Expanded billing transparency, dark mode across apps, and production stability fixes ## Billing transparency, dark mode, and stability fixes The pricing page now shows all metered products, dark mode is available on the status page and verification portal, and a round of production fixes improves reliability across the console. ### New features * **Full metered product pricing:** The [pricing page](https://www.truthlocks.com/pricing) now lists all 16 metered products across four categories — Core, MAIP, AI, and Anti-Fraud — so you can see exactly what you're paying for. The pricing calculator has also been expanded with sliders for agents and receipts, and the feature comparison table now includes MAIP, AI, and Anti-Fraud rows. * **Dark mode on status page and verification portal:** The [status page](https://status.truthlocks.com) and [verification portal](https://verify.truthlocks.com) homepage now fully support dark mode, matching your system preference. All components — service cards, uptime bars, subscription forms, navigation, and history views — render correctly in both light and dark themes. ### Updates * **Expanded usage dashboard:** The [console](https://console.truthlocks.com) usage page now tracks 16 metrics organized by product group instead of the previous two, giving you a more detailed view of your consumption across all platform services. * **Error and loading pages:** The console, status page, verification portal, docs, and [Trust Explorer](https://transparency.truthlocks.com) now display polished error, loading, and not-found pages instead of raw framework defaults — improving the experience when something goes wrong or a page is loading. * **Accessibility improvements:** Images on the [Trust Explorer](https://transparency.truthlocks.com) — including issuer logos and profile images — now include descriptive alt text for screen readers. ### Bug fixes * **Invoice date formatting fixed:** Invoice dates in the console billing section were displaying as raw strings instead of formatted dates. Dates now render correctly. * **Brand name consistency:** A remaining instance of "Truthlock" (without the "s") has been corrected to "Truthlocks" across generated route metadata. * **Status page dark mode rendering:** Dark-mode utility classes on the [status page](https://status.truthlocks.com) were being ignored due to a missing Tailwind configuration. Dark mode styles now apply correctly. * **Website header navigation fixed:** A broken SVG icon in the site header has been corrected and now renders properly. **Week of May 20, 2028** Solution pages and improved PyPI package descriptions ## Solution pages and PyPI package updates Three new solution pages on the website help you find the right starting point for your use case, and all seven AI connector PyPI packages now display full descriptions on PyPI. ### New features * **Solution pages:** Three new pages on [truthlocks.com](https://www.truthlocks.com) — [AI Verification](https://www.truthlocks.com/solutions/ai-verification), [Developers](https://www.truthlocks.com/solutions/developers), and [Enterprise](https://www.truthlocks.com/enterprise) — explain how Truthlocks fits different use cases. Use them to understand which platform capabilities are most relevant to your needs before diving into the docs. ### Updates * **PyPI package descriptions:** All seven framework-specific AI connector packages — [`truthlocks-langchain`](/guides/maip-integrations#ai-model-connectors), [`truthlocks-llamaindex`](/guides/maip-integrations#ai-model-connectors), [`truthlocks-crewai`](/guides/maip-integrations#ai-model-connectors), [`truthlocks-autogen`](/guides/maip-integrations#ai-model-connectors), [`truthlocks-openai`](/guides/maip-integrations#ai-model-connectors), [`truthlocks-anthropic`](/guides/maip-integrations#ai-model-connectors), and [`truthlocks-bedrock`](/guides/maip-integrations#ai-model-connectors) — now render full README descriptions on PyPI (v1.0.1). Previously, the package listing pages were blank. You can now read setup instructions, usage examples, and feature overviews directly on PyPI before installing. **Week of May 13, 2028** Live interactive cryptographic verification demo ## Interactive verification demo A new [live demo page](https://www.truthlocks.com/demo) on the website lets you experience Truthlocks' cryptographic verification workflow hands-on — no account required. ### New features * **Interactive verification demo:** The [demo page](https://www.truthlocks.com/demo) walks you through the full Truthlocks verification flow in four steps: generate a receipt, verify its cryptographic hash, tamper with the data, and see the mismatch detected — all running client-side in your browser using Web Crypto SHA-256. This is the fastest way to understand how Truthlocks works before signing up. Try it at [truthlocks.com/demo](https://www.truthlocks.com/demo). **Week of May 6, 2028** Framework-specific Python packages for AI model connectors ## Framework-specific Python packages for AI connectors The [AI model connectors](/guides/maip-integrations#ai-model-connectors) are now available as seven standalone PyPI packages — one for each supported framework — so you can install only the connector you need. ### New features * **Framework-specific PyPI packages:** Instead of installing a single monolithic package, you can now `pip install` the connector for your framework directly: [`truthlocks-langchain`](/guides/maip-integrations#ai-model-connectors), [`truthlocks-llamaindex`](/guides/maip-integrations#ai-model-connectors), [`truthlocks-crewai`](/guides/maip-integrations#ai-model-connectors), [`truthlocks-autogen`](/guides/maip-integrations#ai-model-connectors), [`truthlocks-openai`](/guides/maip-integrations#ai-model-connectors), [`truthlocks-anthropic`](/guides/maip-integrations#ai-model-connectors), and [`truthlocks-bedrock`](/guides/maip-integrations#ai-model-connectors). Each package wraps the core MAIP AI connectors library and pulls in only the dependencies for that framework — keeping your environment lean. All packages are published at v1.0.0 on PyPI. See the [supported frameworks table](/guides/maip-integrations#supported-frameworks) for install commands. **Week of April 29, 2028** Brand consistency fixes, URL redirects, and structured API error responses ## Brand consistency and API error handling Corrected branding across authentication pages, fixed a broken URL path on the website, and improved API gateway error responses for a more predictable developer experience. ### Updates * **Structured API error responses:** The API gateway now returns [RFC 7807 Problem Details](https://www.rfc-editor.org/rfc/rfc7807) JSON for `404 Not Found` and `405 Method Not Allowed` errors. If you integrate with the Truthlocks API, error responses on invalid routes now include a consistent `type`, `title`, `status`, and `detail` field — making it easier to handle errors programmatically. See the [error handling guide](/ops/errors) for details. ### Bug fixes * **Brand name corrected on authentication pages:** The company name was displayed as "Truthlock Inc." instead of "Truthlocks Inc." on the [sign-in](https://console.truthlocks.com/auth/sign-in), [sign-up](https://console.truthlocks.com/auth/sign-up), and [verification portal](https://verify.truthlocks.com) login pages, as well as the status page footer. This is now corrected across all pages. * **Website product URL redirect fixed:** Visiting `/products/*` on [truthlocks.com](https://www.truthlocks.com) now correctly redirects to `/product/*`. Previously, these URLs returned a 404. **Week of April 22, 2028** Verification portal navigation fix ## Verification portal stability fix A rendering issue in the [verification portal](https://verify.truthlocks.com) navigation has been resolved. ### Bug fixes * **Verification portal navigation fixed:** The consumer navigation sidebar on the [verification portal](https://verify.truthlocks.com) could fail to render correctly due to a component error, which in some cases prevented the sidebar from loading. This is now fixed — navigation loads reliably for all users. **Week of April 15, 2028** Corrected VS Code extension ID, JetBrains plugin link, and GitHub Action slug ## MAIP integration link and identity fixes Several incorrect identifiers and links on the [Downloads](https://truthlocks.com/resources/downloads) and [Plugins](https://truthlocks.com/resources/plugins) pages have been corrected, so install links and marketplace listings now resolve properly. ### Bug fixes * **VS Code extension marketplace ID corrected:** The [VS Code extension](/guides/maip-integrations#vs-code-extension) was listed with an incorrect marketplace identifier, which meant the install link from the Downloads and Plugins pages did not resolve. The extension ID is now correct, and the marketplace listing also displays the proper Truthlocks brand icon. * **JetBrains plugin link fixed:** The [JetBrains plugin](/guides/maip-integrations#jetbrains-plugin) link on the Plugins page was returning a 404. It now points to the correct repository where you can download and install the plugin. * **GitHub Action slug corrected:** The [MAIP GitHub Action](/guides/maip-integrations#github-action) was referenced with an incorrect slug on the Downloads page. The link now points to the correct Action, so you can find and install it from the GitHub Marketplace without issues. **Week of April 8, 2028** Docker images for MAIP services and VS Code extension metadata ## Docker images for MAIP services Four MAIP integration packages are now available as Docker images, and a new Docker Compose file lets you run the full MAIP stack locally with a single command. The VS Code extension has also been updated with improved marketplace metadata. ### New features * **MAIP Docker images:** Official Docker images are now available for the [CLI](/guides/protect-cli), [MCP Server](/guides/maip-integrations#mcp-server), [event streaming gateway](/guides/maip-integrations#event-streaming), and [Slack integration](/guides/maip-integrations#slack). Pull and run any image individually, or use the new Docker Compose file to spin up the entire MAIP integration stack in one step. This is the fastest way to get started with self-hosted MAIP integrations. Images are available on the [Downloads](https://truthlocks.com/resources/downloads) page. See the [Docker deployment guide](/guides/maip-integrations#docker) for setup instructions. * **Docker Compose for MAIP:** A single `docker-compose` file orchestrates all five MAIP service containers — the CLI, MCP Server, event streaming gateway, Slack integration, and the core machine identity service — so you can run the full stack locally for development and testing. See the [full Docker Compose example](/guides/maip-integrations#run-the-full-maip-stack) to get started. ### Updates * **VS Code extension marketplace metadata:** The [VS Code extension](/guides/maip-integrations#vs-code-extension) now includes an updated README and changelog on the Visual Studio Marketplace, making it easier to understand what the extension does before installing it. **Week of October 23, 2027** SDK and integration package namespace corrections for Go modules, Python packages, and Neovim plugin ## SDK and integration package references corrected Incorrect organization references in several SDK and integration packages have been fixed. If you previously encountered import errors or broken repository links when installing Go modules, Python packages, or the Neovim plugin, those are now resolved. ### Bug fixes * **Go module paths corrected:** The [Kafka connector](/guides/maip-integrations#kafka-connector) and [event streaming gateway](/guides/maip-integrations#event-streaming) Go modules were referencing an incorrect GitHub organization in their module paths, which could cause `go get` and `go mod tidy` to fail. Both packages now resolve to the correct namespace. * **Python package URLs fixed:** The [Delta Lake plugin](/guides/maip-integrations#delta-lake-plugin), [DVC plugin](/guides/maip-integrations#dvc-plugin), [MLflow plugin](/guides/maip-integrations#mlflow-plugin), and [AI model connectors](/guides/maip-integrations#ai-model-connectors) had incorrect repository URLs in their package metadata. Links from PyPI now point to the correct source repositories. * **Neovim plugin references updated:** The [Neovim plugin](/guides/maip-integrations#neovim-plugin) documentation and source code contained outdated organization references. All help docs and Lua source files now link to the correct repository. * **GitHub Action references corrected:** The [MAIP GitHub Action](/guides/maip-integrations#github-action) source files had incorrect organization references in check annotations and comment templates. CI output now displays the correct links. **Week of October 16, 2027** Corrected package names, organization links, and documentation URLs on the website resources pages ## Website resources pages fixed Several links and references on the public-facing resources pages were pointing to incorrect destinations. These have been corrected so you can find the right packages, repositories, and documentation on the first click. ### Bug fixes * **Corrected package names and install commands:** The [Downloads](https://truthlocks.com/resources/downloads) page was displaying incorrect package names, which could cause failed installs if you copied the commands directly. The correct package names are now shown. * **Fixed GitHub organization links:** Links to the Truthlocks GitHub organization on the [Integrations](https://truthlocks.com/resources/integrations) and [Plugins](https://truthlocks.com/resources/plugins) pages were pointing to the wrong organization. All repository links now resolve to the correct source. * **Fixed documentation links on resources pages:** Several "View docs" links on the [Integrations](https://truthlocks.com/resources/integrations), [Downloads](https://truthlocks.com/resources/downloads), and [Plugins](https://truthlocks.com/resources/plugins) pages were broken or pointing to outdated paths. All links now point to the correct documentation pages. * **Homepage CLI section updated:** The CLI install command on the [homepage](https://www.truthlocks.com) hero section now references the correct package name. **Week of October 9, 2027** Build infrastructure restored to ensure uninterrupted platform deployments ## Build infrastructure restored A configuration issue temporarily disrupted the platform's deployment pipeline. The affected build and packaging files have been restored, ensuring platform updates continue to ship without delay. ### Bug fixes * **Deployment pipeline restored:** A misconfiguration caused critical build and packaging files to be overwritten with empty content, which blocked new deployments from building and shipping. All affected files have been restored to their correct state. No user-facing functionality was affected, but this fix ensures that platform updates and patches resume shipping on schedule. **Week of October 2, 2027** Console and verification portal UX improvements, SEO sitemaps, API playground fix, and audit log reliability ## Console UX polish, SEO improvements, and reliability fixes A round of usability, discoverability, and reliability improvements across the console, verification portal, API playground, and public-facing sites. ### Updates * **Modern notifications in console and verification portal:** Browser-native alert and confirmation dialogs have been replaced with toast notifications and inline confirmation modals across the [console](https://console.truthlocks.com) and [verification portal](https://verify.truthlocks.com). Actions like revoking attestations or deleting resources now show polished in-app confirmations instead of default browser popups. * **Sitemaps for all public apps:** The [documentation](https://docs.truthlocks.com), [status page](https://status.truthlocks.com), and [transparency portal](https://transparency.truthlocks.com) now serve XML sitemaps, improving search engine indexing and discoverability. * **Website footer updated:** The [truthlocks.com](https://www.truthlocks.com) footer has been refreshed with current navigation links and branding. ### Bug fixes * **API reference playground requests unblocked:** The [interactive API playground](/api-reference/attestations/mint) was blocking live requests due to a Content Security Policy misconfiguration. API calls from the playground now work as expected in both Sandbox and Production environments. * **Website contact form fixed:** The contact form on [truthlocks.com](https://www.truthlocks.com) was returning 500 errors. The form now submits successfully. * **Audit log API routing corrected:** [Audit log](/api-reference/audit/query) queries and exports could intermittently fail due to a backend routing misconfiguration. Audit log data now returns reliably. **Week of September 25, 2027** Q3 2027 platform recap — everything that shipped since the MAIP and Anti-Fraud launches ## Q3 2027 platform recap With the [instant issuer activation](/api-reference/issuers/create) rollout now complete, here is a summary of everything that shipped this quarter — from new platform capabilities to security and compliance improvements. ### New features shipped this quarter * **Compliance exports:** Export audit data formatted for SOC 2, GDPR, and HIPAA directly from the console or API, in JSON or CSV. Requires the Compliance Pack add-on. See the [compliance exports guide](/guides/compliance-exports). * **Africa (AF) data residency region:** A third data residency region in Cape Town is now available for tenants subject to POPIA or other African data sovereignty requirements. See [data residency](/security/data-residency). * **Custom SMTP for email delivery:** Enterprise and government tenants can route all platform emails through their own SMTP server. See [email delivery](/security/email-delivery). * **Account security controls:** Enable TOTP-based multi-factor authentication, change your password, and manage active sessions from your account settings. See the [account security guide](/guides/account-security). * **Email verification page:** The post-signup email verification flow now works end to end with a dedicated confirmation page. ### Updates * **Instant issuer activation:** New issuers now activate immediately at the **Basic** trust level — no manual approval required. Start [minting attestations](/api-reference/attestations/mint) as soon as you [create an issuer](/api-reference/issuers/create). The [quickstart](/quickstart), [Trust Explorer](/guides/truth-explorer), [RBAC permissions](/security/rbac), [issuer applications](/guides/issuer-applications), and [B2G Procurement Pack](/packs/enterprise/b2g-procurement) all reflect this change. * **SIEM integration expanded:** Step-by-step setup instructions now cover five providers — Splunk, Datadog, AWS CloudWatch, Elastic/ELK, and custom webhooks with HMAC signature verification. See the [SIEM integration guide](/guides/siem-integration). * **Issuer applications clarified:** Applications are now only needed to upgrade from the default Basic tier to a higher trust level such as Verified Organization or Government Entity. See the [issuer applications guide](/guides/issuer-applications). * **MAIP and Anti-Fraud production verified:** All 44 [Machine Identity endpoints](/guides/machine-identity) and all five [Anti-Fraud detection paths](/guides/risk-signals) — including [deepfake scanning](/guides/deepfake-detection), [ATO detection](/guides/ato-detection), and [velocity scoring](/guides/velocity-scoring) — are confirmed stable in production. * **SDKs finalized:** The [JavaScript](/sdk/js), [Go](/sdk/go), and [Python](/sdk/python) SDKs are published with full API coverage, typed interfaces, and correct documentation links. ### Bug fixes * **MAIP GitHub Action installs reliably:** Fixed a missing package specifier that could cause `pnpm install --frozen-lockfile` to fail in CI. See [MAIP integrations](/guides/maip-integrations#github-action). * **Proof bundle downloads restored:** Proof bundle downloads are no longer blocked by incorrect billing entitlement checks. * **Public verification works without authentication:** The [verification portal](https://verify.truthlocks.com) no longer returns 401 errors for anonymous lookups. **Week of September 18, 2027** Instant issuer activation rollout complete and MAIP GitHub Action dependency fix ## Issuer activation rollout complete The instant issuer activation model is now fully rolled out across the entire platform. A dependency fix also restores reliable installs for the MAIP GitHub Action. ### Updates * **Instant issuer activation rollout complete:** Over the past three weeks, every platform surface has been updated to reflect the new issuer onboarding model — new issuers activate immediately at the **Basic** trust level with no manual approval gate. This includes the [quickstart](/quickstart), [introduction](/introduction), [Trust Explorer](/guides/truth-explorer), [transparency settings](/guides/transparency-settings), [RBAC permissions](/security/rbac), [issuer applications](/guides/issuer-applications), and [B2G Procurement Pack](/packs/enterprise/b2g-procurement). If you were waiting to try the platform, you can now [create an issuer](/api-reference/issuers/create) and start [minting attestations](/api-reference/attestations/mint) immediately. ### Bug fixes * **MAIP GitHub Action installs reliably:** Fixed a missing package specifier in the [MAIP GitHub Action](/guides/maip-integrations#github-action) dependency manifest that could cause `pnpm install --frozen-lockfile` to fail. If you were seeing install failures in CI when using the GitHub Action, this is now resolved. **Week of September 11, 2027** Compliance exports, Africa data residency, custom SMTP, account security, and issuer onboarding alignment ## Compliance exports, Africa data residency, and account security New compliance reporting, a third data residency region, custom email infrastructure for enterprise tenants, expanded SIEM provider coverage, self-service account security controls, and issuer onboarding alignment across remaining guides. ### New features * **Compliance exports:** Export your audit data in framework-specific formats for SOC 2, GDPR, and HIPAA reporting. Each report includes the evidence auditors need — control mappings, data processing records, or security audit trails — formatted for the target framework. Generate reports from **Settings > Audit > Export** in the console or via the API, in JSON or CSV. Requires the Compliance Pack add-on. See the [compliance exports guide](/guides/compliance-exports). * **Africa (AF) data residency region:** A third data residency region is now available in Cape Town, South Africa, for tenants subject to POPIA or other African data sovereignty requirements. Your region is assigned automatically based on your organization's country code. All tenant data — users, attestations, evidence, files, billing records, and audit logs — stays in the selected region, with HTTP 409 enforcement if a request is routed to the wrong region. See [data residency](/security/data-residency). * **Custom SMTP for email delivery:** Enterprise and government tenants can now route all platform emails through their own SMTP server instead of the default AWS SES infrastructure. Configure your SMTP host, port, and credentials from **Settings > Email** in the console. This is useful for organizations that require emails to originate from their own mail systems. See [email delivery](/security/email-delivery). * **Account security controls:** You can now enable multi-factor authentication (TOTP), change your password, and manage active sessions directly from your account security settings. MFA works with any authenticator app (Google Authenticator, Authy, 1Password). Session management lists all active sessions by device and location, and lets you sign out other sessions if you suspect unauthorized access. See the [account security guide](/guides/account-security). ### Updates * **SIEM integration guide with provider-specific setup:** The [SIEM integration guide](/guides/siem-integration) now includes step-by-step setup instructions for five providers — Splunk (HTTP Event Collector), Datadog (Log Management API), AWS CloudWatch, Elastic/ELK, and custom webhooks with HMAC signature verification. You can also update or delete existing SIEM destinations via the API. Requires the Enterprise tier. * **Email bounce handling and suppression:** The platform now automatically suppresses email addresses that hard bounce or receive spam complaints. Suppressed addresses are checked before every send attempt, and the API returns an `EMAIL_SUPPRESSED` error code if a recipient is on the suppression list. This improves deliverability and protects your sender reputation. See [email delivery](/security/email-delivery). * **Console session management for administrators:** Tenant administrators can now view and revoke active console sessions from **Settings > Sessions**. Each session shows the device, browser, location, and last-active timestamp. Revoke any session to immediately sign out that user. See [account security](/guides/account-security). * **Issuer applications are now for trust tier upgrades only:** The [issuer application](/guides/issuer-applications) guide has been updated to clarify that new issuers activate immediately at the **Basic** trust level — no application required. Applications are only needed when you want to upgrade to a higher tier such as **Verified Organization**, **Government Entity**, or **Accredited Institution**. The application workflow, evidence upload steps, and approval process remain the same. * **Government onboarding reflects instant activation:** The [B2G Procurement Pack](/packs/enterprise/b2g-procurement) onboarding flow now shows that government agency issuers are activated at the Basic tier as soon as they are created during the onboarding wizard. Agencies that need a higher trust tier can submit an [issuer application](/guides/issuer-applications) after onboarding — there is no longer a waiting period before minting. **Week of September 4, 2027** Trust Explorer tier system and RBAC updates to match streamlined issuer onboarding ## Trust Explorer tiers and RBAC alignment Following last week's instant issuer activation change, the public [Trust Explorer](https://transparency.truthlocks.com) and [RBAC permission model](/security/rbac) have been updated to reflect the new onboarding flow. ### Updates * **Trust Explorer now shows Basic and Verified tiers:** The public issuer directory on the [Trust Explorer](/guides/truth-explorer) previously displayed "Pending" and "Verified" badges. Since new issuers are now active immediately, the "Pending" tier has been replaced with **Basic** — the default trust level assigned on creation. Organizations that complete governance review are shown as **Verified**. To upgrade from Basic to Verified, submit an [issuer application](/guides/issuer-applications). See [transparency settings](/guides/transparency-settings#verification-tiers). * **Governance permission scope clarified:** The `governance:approve` [RBAC permission](/security/rbac) previously described as "Approve pending issuers" now reads "Approve governance requests" — reflecting that manual approval is no longer part of issuer creation. This permission applies to trust tier upgrade reviews and other governance actions. No changes to how the permission works; this is a label update only. **Week of August 28, 2027** Streamlined issuer onboarding — new issuers activate instantly without manual approval ## Streamlined issuer onboarding New issuers are now activated immediately on creation, removing the previous manual approval gate from the getting-started flow. ### Updates * **Instant issuer activation:** When you [create an issuer](/api-reference/issuers/create), it now returns `status: "ACTIVE"` immediately — no waiting for a governance admin to approve it. You can start [minting attestations](/api-reference/attestations/mint) right away after registering your issuer and signing key. The [quickstart](/quickstart) and [introduction](/introduction) now reflect this streamlined flow. * **Issuer applications for higher trust tiers:** Manual review is now reserved for organizations that need an elevated trust tier — **Verified Organization**, **Government Entity**, or **Accredited Institution**. Submit an [issuer application](/guides/issuer-applications) when you're ready to upgrade from the default **Basic** tier. Basic-tier issuers have full minting and signing capabilities. **Week of August 21, 2027** Public verification reliability, email verification flow, proof bundle downloads, and platform stability improvements ## Public verification, email flow, and stability improvements A round of reliability and usability fixes across the verification portal, signup flow, proof bundles, and platform infrastructure — resolving several issues that affected end users in production. ### New features * **Email verification page:** The post-signup email verification flow now works end to end. Clicking the verification link in your email lands on a dedicated setup page that confirms your account — previously this returned a 404. The [sign-in page](https://console.truthlocks.com/auth/sign-in) also now shows a "check your email" banner after signup. * **Issuer auto-approval on registration:** New [issuers](/api-reference/issuers/create) are now activated immediately upon creation, removing the previous manual review step. You can start minting attestations right away after registering your issuer. ### Updates * **Proof bundle downloads restored:** [Proof bundle](/specification/proof-bundle) downloads were failing for some users due to an incorrect billing entitlement check. Downloading proof bundles is now unrestricted — billing is enforced at attestation creation time, not on read. Developer plan accounts also now include 100 proof bundle downloads. * **Public verification no longer requires authentication:** The [verification portal](https://verify.truthlocks.com) was returning 401 errors for anonymous verification lookups. Public verification now works without authentication as intended — anyone with a verification link can confirm an attestation's validity. * **Transparency log checkpoints available across all tenants:** The [transparency log](/specification/proof-bundle) checkpoint endpoint was returning empty results in some cases. Checkpoints are now correctly aggregated across all tenants, so inclusion proofs resolve reliably. * **Email notifications working in production:** Several email templates — including email verification, issuer approval, incident notifications, and password reset — had broken placeholders that prevented delivery. All notification emails now render correctly with the right content. * **Marketing page signup links fixed:** Seven call-to-action buttons across the pricing, product, and calculator pages on [truthlocks.com](https://www.truthlocks.com) were linking to a non-existent signup URL. All CTAs now point to the correct [sign-up page](https://console.truthlocks.com/auth/sign-up). ### Bug fixes * **Key generation errors for new tenants resolved:** New tenants could encounter a 500 error when generating their first issuer key because the production environment wasn't auto-created. Environment setup is now automatic on first key generation. * **Audit log writes no longer silently dropped:** Audit log entries triggered by API requests were occasionally lost due to a request lifecycle issue. Audit writes now complete reliably regardless of when the originating request finishes. * **Console dashboard loads correctly:** The tenant console dashboard was returning 401 errors on load. Dashboard data now routes through the correct backend path and loads as expected. * **Cryptographic signing algorithm corrected:** The platform's KMS integration was selecting an incompatible Ed25519 signing algorithm variant, which could cause signature validation errors. The correct algorithm is now used for all signing operations. **Week of August 14, 2027** Full platform production readiness — MAIP and Anti-Fraud both GA with all SDKs, integrations, and detection paths ## Platform production readiness milestone Both major platform tracks — [Machine Identity (MAIP)](/guides/machine-identity) and the [Anti-Fraud Identity Firewall](/guides/risk-signals) — are now available for integration subject to the documented implementation limits with stable APIs, published SDKs, and complete documentation. ### Updates * **Machine Identity stability verified:** All 44 [MAIP API endpoints](/api-reference/machine-identity/agents/register) have been verified stable after the route conflict fixes shipped last week. If you previously experienced intermittent errors with agent registration, session management, or trust score queries, those issues are resolved. No further action is needed. * **Anti-Fraud detection paths complete:** All five detection paths — [direct signal ingestion](/api-reference/risk/ingest-signal), [event normalization](/api-reference/risk/normalize-event), [deepfake scanning](/api-reference/risk/deepfake-scan), [ATO detection](/api-reference/risk/ato-evaluate), and [velocity scoring](/api-reference/risk/velocity-record) — are confirmed stable in production with real-time [webhook notifications](/guides/webhooks#risk-signal-notifications) for signal creation and escalation events. * **SDK packages finalized:** The [JavaScript](/sdk/js), [Go](/sdk/go), and [Python](/sdk/python) SDKs — including the [`@truthlocks/sdk-antifraud`](/guides/risk-signals) package — are published to npm with proper MIT licensing, hardened package contents, and corrected documentation links. * **12 MAIP integrations integration:** All integrations — [Slack](/guides/maip-integrations#slack), [GitHub Action](/guides/maip-integrations#github-action), [Linear](/guides/maip-integrations#linear), [Notion](/guides/maip-integrations#notion), [VS Code](/guides/maip-integrations#vs-code-extension), [JetBrains](/guides/maip-integrations#jetbrains-plugin), [MCP Server](/guides/maip-integrations#mcp-server), [Neovim](/guides/maip-integrations#neovim-plugin), [event streaming](/guides/maip-integrations#event-streaming), [Kafka](/guides/maip-integrations#kafka-connector), [MLflow](/guides/maip-integrations#mlflow-plugin), and [AI model connectors](/guides/maip-integrations#ai-model-connectors) — are available for use. Browse them on the [Integrations hub](https://truthlocks.com/resources/integrations) or the [MAIP integrations guide](/guides/maip-integrations). **Week of August 7, 2027** MAIP stability improvements, SDK security hardening, website navigation, and endpoint path changes ## MAIP stability, SDK hardening, and website navigation A round of stability, security, and usability improvements across the Machine Identity service, published SDKs, and the marketing site — plus two breaking MAIP endpoint path changes and a finalized dataset lineage route. ### Updates * **MAIP API stability improvements:** Resolved route conflicts in the [Machine Identity](/guides/machine-identity) service that could cause certain API requests to return unexpected errors. If you experienced intermittent failures when calling MAIP endpoints — particularly agent registration, session management, or trust score queries — those issues are now fixed. * **SDK package security:** The [JavaScript](/sdk/js), [Go](/sdk/go), and [Python](/sdk/python) SDK packages have been hardened to exclude internal source files and now include proper open-source licensing. No changes to the SDK APIs — this only affects the published package contents. * **Website resources navigation:** The marketing site header now includes a **Resources** dropdown with direct links to the [Integrations hub](https://truthlocks.com/resources/integrations), [Downloads](https://truthlocks.com/resources/downloads), and [Plugins](https://truthlocks.com/resources/plugins) pages — making it easier to discover available tools without navigating through the docs. * **MAIP endpoint path changes:** Two [Machine Identity](/guides/machine-identity) API paths have changed. If you have these routes hardcoded, update them: * `GET /v1/compliance/{entityID}/status` is now `GET /v1/compliance/entities/{entityID}/status` * `GET /v1/datasets/{attestationID}/lineage` is now `GET /v1/datasets/lineage/{datasetId}` The previous paths no longer resolve. See the [compliance API](/api-reference/machine-identity/compliance/reports) and [dataset lineage API](/api-reference/machine-identity/datasets/lineage) references for the current routes. * **Open-source licensing:** The repository-level MIT license file is now in place, so the license link shown on [npm package pages](https://www.npmjs.com/package/@truthlocks/sdk) resolves correctly. ### Bug fixes * **API input validation hardening:** The document status update API now validates input fields against a strict allowlist, closing a potential injection vector. No action needed on your part — this fix is applied server-side. * **Fixed broken links in SDK READMEs:** Four links in the [JavaScript SDK](/sdk/js), [Protect CLI](/guides/protect-action), and [Anti-Fraud SDK](/guides/risk-signals) README files on npm and GitHub were pointing to non-existent documentation pages. All links now resolve to the correct guides. **Week of June 2, 2027** Dataset lineage API reference updated to reflect new endpoint path ## Dataset lineage API reference now reflects new path The [dataset lineage endpoint](/api-reference/machine-identity/datasets/lineage) API reference and OpenAPI specification have been updated to reflect the path change announced last week. ### Updates * **Dataset lineage endpoint path finalized:** The [dataset lineage endpoint](/api-reference/machine-identity/datasets/lineage) now uses `GET /v1/datasets/lineage/{datasetId}` in the API reference and interactive playground. If you bookmarked the old API reference page or copied example code from the docs, update your references to use the new path. The previous path (`GET /v1/datasets/{attestationID}/lineage`) no longer resolves. See the [Machine Identity guide](/guides/machine-identity) for an overview of all MAIP endpoints. **Week of May 26, 2027** Website resource navigation, SDK link fixes, MAIP endpoint path changes, and open-source licensing ## Website navigation, SDK fixes, and MAIP path changes Quality-of-life improvements across the website, published SDKs, and the Machine Identity service — including a breaking endpoint path change for two MAIP routes. ### Updates * **Resources navigation on the website:** The marketing site header now includes a **Resources** dropdown with direct links to the [Integrations hub](https://truthlocks.com/resources/integrations), [Downloads](https://truthlocks.com/resources/downloads), and [Plugins](https://truthlocks.com/resources/plugins) pages — making it easier to discover available tools without navigating through the docs. * **MAIP endpoint path changes:** Two [Machine Identity](/guides/machine-identity) API paths have changed. If you have these routes hardcoded, update them: * `GET /v1/compliance/{entityID}/status` is now `GET /v1/compliance/entities/{entityID}/status` * `GET /v1/datasets/{attestationID}/lineage` is now `GET /v1/datasets/lineage/{attestationID}` The previous paths no longer resolve. See the [compliance API](/api-reference/machine-identity/compliance/reports) and [datasets API](/api-reference/machine-identity/datasets/lineage) references for the current routes. * **Open-source licensing:** The repository-level MIT license file is now in place, so the license link shown on [npm package pages](https://www.npmjs.com/package/@truthlocks/sdk) resolves correctly. Previously it returned a 404. ### Bug fixes * **Fixed broken links in SDK READMEs:** Four links in the [JavaScript SDK](/sdk/js), [Protect CLI](/guides/protect-action), and [Anti-Fraud SDK](/guides/risk-signals) README files on npm and GitHub were pointing to non-existent documentation pages. All links now resolve to the correct guides. **Week of May 19, 2027** MAIP API stability improvements, SDK security hardening, and API input validation ## MAIP API stability, SDK security, and API hardening Stability and security improvements across the Machine Identity service, published SDK packages, and the platform API. ### Updates * **MAIP API stability improvements:** Resolved route conflicts in the [Machine Identity](/guides/machine-identity) service that could cause certain API requests to return unexpected errors. If you experienced intermittent failures when calling MAIP endpoints — particularly agent registration, session management, or trust score queries — those issues are now fixed. * **SDK package security:** The [JavaScript](/sdk/js), [Go](/sdk/go), and [Python](/sdk/python) SDK packages published to npm have been hardened to exclude internal source files and now include proper open-source licensing. No changes to the SDK APIs — this only affects the package contents. ### Bug fixes * **API input validation hardening:** The document status update API now validates input fields against a strict allowlist, closing a potential injection vector. No action is needed on your part — this fix is applied server-side automatically. **Week of May 12, 2027** MAIP integration overview, Neovim command reference, event streaming SDK, MCP Server configuration, and expanded sidebar navigation ## MAIP integration guides, expanded navigation, and cross-linked docs The [MAIP integrations guide](/guides/maip-integrations) now includes full setup instructions, configuration examples, and command references for every integration. The [machine identity guide](/guides/machine-identity) has a new integration overview table, and 28 guide and reference pages are now accessible from the sidebar. ### Updates * **Integration overview in machine identity guide:** The [machine identity guide](/guides/machine-identity) now includes a quick-reference table of all MAIP integrations organized by category — editor plugins, AI assistants, data pipelines, CI/CD, AI frameworks, and team tools — so you can discover available connectors at a glance. * **Neovim plugin command reference:** The [Neovim plugin](/guides/maip-integrations#neovim-plugin) section now documents all five commands (`:MaipReceipt`, `:MaipReceipts`, `:MaipTrust`, `:MaipAgent`, `:MaipSearch`), Telescope fuzzy-finder integration for searching receipts, a lualine-compatible statusline component that displays your agent's trust score, and an `auto_receipt` option that generates a receipt every time you save a buffer — with copy-paste code snippets for lazy.nvim. * **Event streaming Python SDK:** The [event streaming gateway](/guides/maip-integrations#event-streaming) now includes a Python SDK with a backend comparison table and configuration examples for running Kafka, EventBridge, Kinesis, NATS, and Redis Streams simultaneously in a single gateway instance — with built-in deduplication, exponential backoff retries, and Prometheus-compatible metrics at `/metrics`. * **MCP Server configuration:** The [MCP Server](/guides/maip-integrations#mcp-server) section now includes a ready-to-use JSON configuration snippet for connecting AI coding assistants to the MAIP platform. The server exposes 20 tools, 4 resources, and 3 prompts for agent registration, receipt generation, and trust score queries. * **Orchestration guide cross-links:** The [AI orchestration guide](/guides/ai-orchestration) now links directly to the [event streaming gateway](/guides/maip-integrations#event-streaming) and [AI model connectors](/guides/maip-integrations#ai-model-connectors), making it easier to find the right integration when building multi-agent workflows. * **Expanded sidebar navigation:** 28 guide and reference pages — including [account security](/guides/account-security), [AI metadata](/guides/ai-metadata), [privacy center](/guides/privacy-center), [Truth Explorer](/guides/truth-explorer), [transparency settings](/guides/transparency-settings), [custom domains](/guides/custom-domains), [enterprise branding](/guides/enterprise-branding), [SIEM integration](/guides/siem-integration), [data residency](/security/data-residency), [abuse hardening](/security/abuse-hardening), [compliance review](/guides/compliance-review), and [provider routing](/billing/provider-routing) — are now accessible directly from the docs sidebar. **Week of May 5, 2027** Neovim plugin, event streaming gateway, SDKs on npm, and homepage refresh ## Neovim plugin, event streaming, SDKs on npm, and homepage refresh A new Neovim plugin and a multi-backend event streaming gateway join the MAIP integration catalog, all three Truthlocks SDKs are now installable from npm, and the homepage and marketing site have been refreshed with up-to-date platform capabilities. ### New features * **Neovim plugin:** A Lua-native plugin for Neovim brings MAIP receipts, agent management, and trust scores into your editor. Browse and create receipts from Neovim commands, search receipts with Telescope, view agent trust scores in the statusline, and auto-generate receipts on file save or git commit. Install via your preferred plugin manager. See the [MAIP integrations guide](/guides/maip-integrations). * **Event streaming gateway:** A new multi-backend event streaming gateway generates MAIP data-flow receipts for messages flowing through your event-driven pipelines. Supports Kafka, AWS EventBridge, AWS Kinesis, NATS, and Redis Streams — each with built-in deduplication, retry middleware, and operational metrics. See [MAIP integrations](/guides/maip-integrations). * **SDKs published to npm:** The [JavaScript](/sdk/js), [Go](/sdk/go), and [Python](/sdk/python) SDKs — including the new [`@truthlocks/sdk-antifraud`](/guides/risk-signals) package — are now published to npm and available for install. Each package includes full API coverage, typed interfaces, and a README with quickstart examples. * **Use Cases page:** A new [Use Cases](https://www.truthlocks.com/use-cases) page on the marketing site explains how to apply Truthlocks across common scenarios — from content protection and credential verification to regulatory compliance and supply chain integrity. Use it to find the right starting point for your integration. ### Updates * **Homepage refresh:** The [homepage](https://www.truthlocks.com) now features an updated capabilities grid highlighting all core platform areas — attestations, receipts, machine identity, anti-fraud, compliance, and billing — alongside corrected pricing information and direct navigation to Machine Identity (MAIP) resources. * **Product and solution pages:** Five new deep-dive pages on the marketing site cover attestation workflows, fraud prevention, compliance automation, identity verification, and enterprise trust — giving prospective users a clearer picture of how the platform fits their stack before signing up. * **MAIP launch blog post:** A dedicated [blog post](https://www.truthlocks.com/blog) walks through the Machine Identity launch — what MAIP is, why it matters for AI agent governance, and how to get started with agent registration and trust scoring. * **SEO metadata improvements:** Page titles, descriptions, and Open Graph tags across all public-facing pages have been audited and corrected for accuracy, improving search engine discoverability and social media previews. **Week of April 28, 2027** Integrations hub, downloads page, and console navigation improvements ## Integrations hub, downloads, and console navigation A new set of pages make it easier to discover MAIP integrations, download tools, and navigate the console. ### New features * **Integrations hub:** A dedicated [Integrations](https://truthlocks.com/resources/integrations) page lets you browse and filter all 28 MAIP integrations in one place — organized by category with search. Find the right connector for your stack without digging through individual guides. See the full list of available integrations in the [MAIP integrations guide](/guides/maip-integrations). * **Downloads page:** A new [Downloads](https://truthlocks.com/resources/downloads) page collects the CLI, SDKs, IDE plugins, and Docker images into a single reference with copy-to-clipboard install commands. * **Plugins page:** A new [Plugins](https://truthlocks.com/resources/plugins) page highlights the VS Code extension and JetBrains plugin alongside all available CI and pipeline plugins. ### Updates * **Console navigation icons:** The Machine Identity and Anti-Fraud sections in the console sidebar now display dedicated icons, making it faster to find the right section at a glance. * **Homepage CLI hero:** The homepage now includes an interactive CLI section with a terminal animation and copy-to-clipboard, so you can get started with the Truthlocks CLI directly from the landing page. **Week of April 21, 2027** Anti-Fraud case management, risk evaluation engine, fraud receipt types, evidence packs, and anti-fraud SDK ## Anti-Fraud case management and risk evaluation engine The [Anti-Fraud Identity Firewall](/guides/risk-signals) now includes a full case management workflow, a unified risk evaluation engine with policy-based decisions, four fraud-specific receipt types, and a dedicated TypeScript SDK — closing the loop from signal detection through investigation and response. ### New features * **Risk evaluation engine:** A new [`POST /v1/risk/evaluate`](/api-reference/risk/evaluate) endpoint combines signal ingestion, policy evaluation, and decision recording in a single call. Submit a signal and receive an immediate decision — `allow`, `challenge`, `block`, or `review` — based on your tenant's active policy rules. Optionally mint a `fraud_decision_receipt` for non-repudiation by passing `mint_receipt: true` with your issuer credentials. * **Risk decision policy rules:** Define tenant-scoped policy rules with configurable thresholds (score ranges, signal type matching, subject type filtering) and actions (`allow`, `challenge`, `block`, `review`, `alert`). Rules are evaluated by priority, with the highest-priority match winning. Five built-in templates are included out of the box — `default_ato`, `default_deepfake`, `default_velocity`, `strict_fraud`, and `compliance_mode` — so you can start with sensible defaults and customize from there. * **Fraud receipt types:** Four new platform receipt types are available for fraud-related events — `fraud_decision_receipt` (records allow/challenge/block/review decisions), `ato_alert_receipt` (records ATO alert events), `risk_block_receipt` (proves an action was blocked due to fraud risk), and `deepfake_detection_receipt` (records deepfake scan results). These receipts provide a cryptographic audit trail for every fraud decision. See [receipt types](/api-reference/receipts/list-types). * **Case management:** Open, triage, and resolve fraud cases from the **Risk & Fraud > Cases** console page. Each case has a severity level, assignee, status workflow, and a full event timeline with notes. Cases are automatically numbered (CASE-YYYY-NNNN) and sorted by severity. Add notes, change status, and track the full investigation history from the case detail view. Cases are also available via the API at `POST /v1/risk/cases` and `GET /v1/risk/cases`. * **Evidence packs:** Generate a complete evidence bundle for any fraud case via `POST /v1/risk/cases/{id}/evidence-pack`. The pack collects all risk signals, decisions, ATO profiles, deepfake scan results, velocity windows, and case events for the subject into a single JSON document — ready for your compliance team or external review. * **Block and challenge actions:** Two new endpoints let you take immediate action on a subject — [`POST /v1/risk/block`](/api-reference/risk/evaluate) blocks a subject and automatically quarantines them, while `POST /v1/risk/challenge` records a challenge decision requiring step-up authentication. Query all decisions via `GET /v1/risk/decisions` with filtering and pagination. * **Quarantine management:** Blocked subjects are automatically quarantined. Check a subject's quarantine status via `GET /v1/risk/quarantine/{subject_id}` or release them via `DELETE /v1/risk/quarantine/{subject_id}`. * **Customer risk dashboard:** A new **Risk & Fraud > Dashboard** page in the console shows eight key metrics at a glance — total signals, high-risk signals, decisions made, subjects blocked, subjects challenged, signals under review, open cases, and critical cases. * **Fraud SIEM export:** Export fraud signal and decision data in JSON, CSV, CEF, or LEEF format via `POST /v1/risk/siem/export`. Poll for completion via `GET /v1/risk/siem/export/{id}`. Use this to feed fraud data into your existing SIEM or security operations workflow. * **Tenant risk configuration:** Configure your tenant's risk thresholds — auto-case creation, automatic blocking, and challenge triggers — from **Settings > Risk** in the console or via `GET /PUT /v1/risk/config`. Toggle switches and threshold sliders let you tune the system without code changes. * **Anti-fraud TypeScript SDK:** A new [`@truthlocks/sdk-antifraud`](https://www.npmjs.com/package/@truthlocks/sdk-antifraud) package provides 12 methods covering the full anti-fraud workflow — `ingestSignal`, `listSignals`, `evaluate`, `evaluateATO`, `getATOProfile`, `recordVelocity`, `blockSubject`, `getQuarantineStatus`, `createCase`, `listCases`, `generateEvidencePack`, and `deepfakeScan`. ### Updates * **API key environment isolation:** API keys now enforce strict environment boundaries. Production keys (`tl_live_` prefix) are rejected in sandbox environments, and sandbox keys (`tl_test_` prefix) are rejected in production. This prevents accidental cross-environment calls. See [environments](/environments). * **Security hardening:** Resolved 21 findings from a security audit — including stricter JWT validation, removal of `unsafe-eval` from Content Security Policies, CORS restrictions to explicit origin allowlists, file upload size limits, SAML and OIDC redirect URL allowlists, and upgraded referrer policies to `strict-origin-when-cross-origin` across all apps. **Week of April 14, 2027** Machine Identity (MAIP) generally available — agent registry, 12 integrations, trust scoring, AI orchestration, and console dashboards ## Machine Identity (MAIP) — generally available The [Machine Identity](/guides/machine-identity) platform is now generally available. MAIP gives your AI agents, pipelines, and automated systems a verifiable identity — with cryptographic receipts, trust scoring, compliance checks, and a full audit trail. This release includes the core service, 12 integrations, console dashboards, usage metering, and platform security hardening. ### New features * **Agent identity registry:** Register AI agents with the platform and manage their full lifecycle — create, update, suspend, and revoke. Each agent gets a unique MAIP identifier and an Ed25519 keypair for signing receipts. Rotate keys on demand or mark a key as compromised to auto-suspend the agent. See the [Machine Identity guide](/guides/machine-identity) and the [register agent endpoint](/api-reference/machine-identity/agents/register). * **Agent sessions and tool access:** Create short-lived, scope-bound sessions for agents with automatic expiry and session handoff between agents. Register tools with risk levels and enforce least-privilege access controls — including rate limiting, scope validation, and approval gating for dangerous operations. See [Agent Authorization](/guides/agent-authorization) and the [sessions API](/api-reference/machine-identity/sessions/create). * **Trust scores and multi-witness attestation:** Compute trust scores for any agent based on receipt history, compliance status, and peer attestations. Create witness groups where multiple agents independently attest to a claim, with weighted consensus scoring. See [Trust Scores](/guides/trust-scores) and the [trust scores API](/api-reference/machine-identity/trust-scores/get). * **Truth claims and document verification:** Create truth claims linked to receipts, with multi-verifier scoring and consensus status (confirmed, disputed, or inconclusive). Verify documents through a four-stage pipeline — upload, extraction, AI verification, and truth claim creation — with each stage chained via receipt linking. See the [truth claims API](/api-reference/machine-identity/truth-claims/create). * **Compliance framework:** Run compliance checks against GDPR, SOC 2, HIPAA, AI Act, and PCI-DSS with continuous compliance chains and period-based reporting. Generate compliance reports that aggregate check results by entity and regulation. See the [compliance API](/api-reference/machine-identity/compliance/create-check). * **AI orchestration and workflows:** Coordinate multi-agent tasks using sequential, parallel, hierarchical, or competitive execution patterns. Define reusable workflows with JSON step definitions and run them on demand. The LLM integration layer generates privacy-preserving receipts for every inference call — hashing prompts and responses without storing content. See [AI Orchestration](/guides/ai-orchestration) and the [orchestrations API](/api-reference/machine-identity/orchestrations/execute). * **Safety guardrails:** Evaluate agent actions against configurable guardrails — prompt injection detection, PII scanning, toxicity filtering, bias checks, hallucination scoring, and budget enforcement. Circuit breakers auto-trip when guardrail violations exceed thresholds. See the [guardrails API](/api-reference/machine-identity/guardrails/check). * **Dataset and model attestation:** Attest datasets with Merkle tree chunking and transformation tracking. Attest ML models with framework, architecture, hyperparameter, and metric metadata. Both automatically create data lineage edges so you can trace provenance upstream and downstream. See the [datasets API](/api-reference/machine-identity/datasets/attest) and the [models API](/api-reference/machine-identity/models/attest). * **Cross-tenant delegation:** Offer and accept bilateral trust delegations between tenants, with configurable depth limits and time-to-live. Each delegation step generates a receipt chain for auditability. See [Cross-Tenant Delegation](/guides/cross-tenant-delegation) and the [delegation API](/api-reference/machine-identity/delegations/offer). * **Signed agent receipts:** Every agent action generates a cryptographically signed receipt — covering nine receipt types including genesis, delegation, action, revocation, data attestation, model attestation, compliance, truth claim, and verification. Receipts are chained via `previous_receipt_id` for tamper-evident audit trails. * **Policy engine:** Define tenant-level policies with conditions (trust score thresholds, scope restrictions, agent type, delegation depth) and effects (allow, deny, or require approval). Evaluate policies in real time before any agent action. See the [policies API](/api-reference/policies/evaluate). * **Anomaly detection:** The platform tracks behavioral baselines for each agent and scores deviations on a 0–1 scale. Report and resolve anomalies through the [anomaly API](/api-reference/machine-identity/anomalies/report). * **Console dashboards:** Six new pages in the tenant console — agent registry, sessions, trust scores, delegations, orchestrations, and compliance checks — give you full visibility into your MAIP deployment without leaving the browser. * **Usage metering and plan quotas:** All MAIP operations — receipts, compliance checks, sessions, tool invocations, witness attestations, truth claims, document verifications, dataset and model attestations, orchestrations, workflows, delegations, and anomaly reports — count against your plan's included quotas. See your current usage on the [billing usage page](/api-reference/billing/usage). ### Integrations * **Slack:** Slash commands (`/maip-receipt`, `/maip-trust`, `/maip-agent`, `/maip-help`) let your team query receipts, trust scores, and agent status directly from Slack. Interactive Block Kit layouts display receipt details, risk summaries, and dashboards inline. * **GitHub Action:** Automatically generate MAIP receipts for commits, pull requests, releases, CI runs, and build artifacts. Verification results appear as GitHub Check Runs with trust score badges on your PRs. * **Linear:** Issue and comment events auto-create MAIP receipts. Verify receipts and post trust scores as comments, with bidirectional sync between Linear and the MAIP platform. * **Notion:** Automatically creates Receipts, Agents, and Trust Scores databases in your workspace. Syncs receipts incrementally, generates audit report pages, and updates Notion in real time via webhooks. * **VS Code extension:** A sidebar panel for browsing receipts, auto-generating receipts from your editor, and viewing trust data — available from the VS Code marketplace. * **JetBrains plugin:** MAIP integration for IntelliJ, PyCharm, and WebStorm with the same receipt browsing and generation capabilities as the VS Code extension. * **MCP Server:** A Model Context Protocol server exposing 20 tools, 4 resources, and 3 prompts for AI assistants to interact with the MAIP platform. * **AI model connectors:** Python connectors for LangChain, LlamaIndex, CrewAI, AutoGen, OpenAI, Anthropic, and AWS Bedrock. Every AI model call automatically generates a receipt with token counts, cost estimates, and SHA-256 content hashes. * **Kafka connector:** Go middleware that auto-generates MAIP data-flow receipts for Kafka messages with batched flushing and operational metrics. * **MLflow plugin:** Python plugin that generates cryptographic receipts for every MLflow model run, providing provenance proof for your ML experiments. * **DVC plugin:** Python plugin for creating MAIP receipts on DVC data versioning operations. * **Delta Lake plugin:** Python plugin for generating receipts on Delta Lake table operations. ### Updates * **Security hardening:** Stricter Content Security Policies across all public-facing apps, tighter CORS restrictions, JWT validation improvements, and file upload size limits. Referrer policies upgraded to `strict-origin-when-cross-origin` across all apps. **Week of April 7, 2027** Interactive API playground for all 44 Machine Identity (MAIP) endpoints ## MAIP interactive API playground All 44 Machine Identity (MAIP) API endpoints now have full interactive playground support. You can build requests, switch between Sandbox and Production environments, and send them directly from the docs — no external tool needed. ### New features * **Interactive playground for all MAIP endpoints:** Every endpoint across [Machine Agents](/api-reference/machine-identity/agents/register), [Agent Sessions & Tools](/api-reference/machine-identity/sessions/create), [Trust & Witness](/api-reference/machine-identity/trust-scores/get), [Truth Claims & Documents](/api-reference/machine-identity/truth-claims/create), [Compliance & Anomalies](/api-reference/machine-identity/compliance/create-check), [Datasets & Models](/api-reference/machine-identity/datasets/attest), [Orchestrations & Workflows](/api-reference/machine-identity/orchestrations/execute), [Guardrails & Delegation](/api-reference/machine-identity/guardrails/check), and [Observability](/api-reference/machine-identity/observability/events) now includes a playground where you can compose and send live API requests. This covers agent registration, session management, trust score queries, witness attestation, compliance checks, orchestration execution, guardrail evaluation, and observability queries. * **OpenAPI specification for MAIP:** A complete OpenAPI 3.0 specification now backs all MAIP endpoints, enabling accurate request/response schemas, parameter validation, and authentication configuration in the playground. The spec supports both `X-API-Key` and Bearer JWT authentication methods. ### Updates * **MAIP guide pages updated:** The [Machine Identity](/guides/machine-identity), [Agent Authorization](/guides/agent-authorization), [Trust Scores](/guides/trust-scores), [Cross-Tenant Delegation](/guides/cross-tenant-delegation), and [AI Orchestration](/guides/ai-orchestration) guides now link to the interactive playground, making it easier to try endpoints while reading the documentation. **Week of July 31, 2027** Real-time webhook notifications for risk signals and unified detection path navigation ## Risk signal webhook notifications You can now receive real-time webhook notifications whenever a risk signal is created or escalated — across all five [Anti-Fraud Identity Firewall](/guides/risk-signals) detection paths. ### New features * **Risk signal webhook events:** Two new webhook event types — `risk.signal.created` and `risk.signal.escalated` — fire whenever a risk signal is ingested or crosses the automatic review threshold. This covers signals from direct ingestion, event normalization, deepfake scans, ATO alerts, and velocity anomalies. Subscribe to `risk.signal.*` to receive both, or pick individually. Each payload includes the `signal_id`, `signal_source`, `signal_type`, `risk_score`, and subject details, so you can trigger automated responses — block a session, notify your security team, or open a fraud case — without polling the API. See the [webhooks guide](/guides/webhooks#risk-signal-notifications). ### Updates * **Unified detection path navigation:** All five detection guides — [risk signals](/guides/risk-signals), [deepfake detection](/guides/deepfake-detection), [ATO detection](/guides/ato-detection), [velocity scoring](/guides/velocity-scoring), and [webhooks](/guides/webhooks) — are now fully cross-linked so you can navigate between detection paths from any guide without returning to the overview. **Week of July 24, 2027** Anti-Fraud Identity Firewall generally available with full multi-language API coverage and end-to-end detection guides ## Anti-Fraud Identity Firewall — generally available The [Anti-Fraud Identity Firewall](/guides/risk-signals) is now generally available. All five detection paths — [direct signal ingestion](/api-reference/risk/ingest-signal), [event normalization](/api-reference/risk/normalize-event), [deepfake scanning](/api-reference/risk/deepfake-scan), [ATO detection](/api-reference/risk/ato-evaluate), and [velocity scoring](/api-reference/risk/velocity-record) — ship with full multi-language API examples (cURL, JavaScript, and Python) and dedicated guides covering end-to-end workflows. ### Updates * **Multi-language API examples across all detection endpoints:** Every Anti-Fraud Identity Firewall endpoint now includes request and response examples in cURL, JavaScript, and Python. This covers [velocity action recording](/api-reference/risk/velocity-record), [velocity window queries](/api-reference/risk/velocity-windows), [anomaly listing](/api-reference/risk/velocity-anomalies), [ATO evaluation](/api-reference/risk/ato-evaluate), [ATO profiles](/api-reference/risk/ato-profile), [ATO alerts](/api-reference/risk/ato-alerts), [deepfake scanning](/api-reference/risk/deepfake-scan), and [scan results retrieval](/api-reference/risk/deepfake-results). * **End-to-end detection guides:** Each detection path now has a dedicated guide with full workflow coverage — from initial API call to signal review in the console. See the [velocity scoring guide](/guides/velocity-scoring), [ATO detection guide](/guides/ato-detection), [deepfake detection guide](/guides/deepfake-detection), and the [risk signals overview](/guides/risk-signals). * **Layered protection patterns:** The [velocity scoring guide](/guides/velocity-scoring#integration-patterns) documents recommended patterns for combining detection paths — use velocity scoring for general abuse (API rate abuse, transaction flooding, registration spam) alongside ATO detection for login-specific security (credential stuffing, subject risk profiles). Both feed into the same unified signal pipeline. * **Webhook notifications for all signal types:** Risk signals created by any of the five detection paths — including velocity anomalies and ATO alerts — can trigger real-time [webhook](/guides/webhooks) notifications, so your security team can respond without polling. **Week of July 17, 2027** Anti-Fraud Identity Firewall feature-complete with five detection paths and custom velocity action types ## Anti-Fraud Identity Firewall — feature-complete The Anti-Fraud Identity Firewall has documented API routes. All five detection paths — [direct signal ingestion](/api-reference/risk/ingest-signal), [event normalization](/api-reference/risk/normalize-event), [deepfake scanning](/api-reference/risk/deepfake-scan), [ATO detection](/api-reference/risk/ato-evaluate), and [velocity scoring](/guides/velocity-scoring) — are integration with a unified signal pipeline. Every path produces the same risk signal records, queryable via the [list signals endpoint](/api-reference/risk-signals/list) and the **Risk & Fraud** console. ### Updates * **Custom velocity action types:** The [velocity scoring engine](/guides/velocity-scoring) supports any action type your application produces — failed logins, API requests, transactions, registrations, password resets, verification requests, or any custom action. Define your own action taxonomy and the platform tracks all of them with the same four-window scoring model and automatic risk signal ingestion at score 60 or above. * **Velocity scoring integration patterns:** You can combine velocity scoring with [ATO detection](/guides/ato-detection) for layered protection — use velocity scoring for general abuse detection (API rate abuse, transaction flooding, registration spam) and ATO detection for focused login security (credential stuffing alerts, subject risk profiles). See the [velocity scoring guide](/guides/velocity-scoring#integration-patterns). * **Five-path unified pipeline:** All five ingestion paths in the Anti-Fraud Identity Firewall — direct ingestion, event normalization, deepfake scanning, ATO detection, and velocity scoring — now produce identical risk signal records. You can query and review signals from any source in one place using the [list signals endpoint](/api-reference/risk-signals/list) or the **Risk & Fraud > Signals** console. See the [ingestion path comparison table](/guides/risk-signals#choosing-an-ingestion-path). **Week of July 10, 2027** Velocity and anomaly scoring engine for multi-window action tracking and automatic risk signal ingestion ## Velocity and anomaly scoring The Anti-Fraud Identity Firewall now includes a velocity and anomaly scoring engine. The platform tracks action frequency per subject across four rolling time windows (1 m, 5 m, 1 h, 24 h), computes a weighted velocity score biased toward burst detection, and automatically ingests a risk signal when the score reaches 60 or above. This is the fifth ingestion path in the risk signal pipeline. ### New features * **Record action endpoint:** A new [`POST /v1/risk/velocity/record`](/api-reference/risk/velocity-record) endpoint accepts any action type and updates rolling window counters for the subject. The response includes current window counts, the computed velocity score, and the `signal_id` if a risk signal was auto-ingested. Use this to evaluate action frequency in real time as events occur. See the [velocity scoring guide](/guides/velocity-scoring). * **Get velocity windows endpoint:** A new [`GET /v1/risk/velocity/{subject_id}`](/api-reference/risk/velocity-windows) endpoint returns all tracked action types for a subject with per-window counts and velocity scores. Use this to inspect a subject's current velocity profile without recording a new action. * **List anomalies endpoint:** A new [`GET /v1/risk/velocity`](/api-reference/risk/velocity-anomalies) endpoint returns a paginated list of subjects with velocity scores above a configurable threshold, sorted by score. Use this to monitor for high-velocity anomalies across your tenant. * **Automatic risk signal ingestion:** When a subject's velocity score reaches 60 or above, the platform automatically ingests a risk signal with `signal_type: "velocity"` into your existing [risk signal pipeline](/guides/risk-signals) — no extra API call needed. ### Updates * **Five-path risk signal pipeline:** The [risk signals guide](/guides/risk-signals) now documents velocity scoring as a fifth ingestion path alongside direct ingestion, event normalization, deepfake scanning, and ATO detection. All five paths produce the same risk signal records. See the [updated ingestion path table](/guides/risk-signals#choosing-an-ingestion-path). **Week of July 3, 2027** Anti-Fraud Identity Firewall fully integrated across all four detection paths ## Anti-Fraud Identity Firewall — fully integrated All four detection paths in the Anti-Fraud Identity Firewall — direct signal ingestion, event normalization, deepfake scanning, and account takeover detection — are now fully cross-linked and navigable as a unified system. ### Updates * **Unified detection workflow:** The [deepfake detection guide](/guides/deepfake-detection) now links directly to the [account takeover detection guide](/guides/ato-detection), and vice versa. You can navigate between all four detection paths from any guide in the Anti-Fraud Identity Firewall without returning to the [risk signals overview](/guides/risk-signals). * **Introduction updated for ATO detection:** The [introduction](/introduction) now lists account takeover detection alongside deepfake scanning, event normalization, and direct signal ingestion as a core Anti-Fraud capability — making it easier for new users to discover ATO detection from the docs landing page. **Week of June 26, 2027** ATO profile and alert endpoints, four-path risk signal pipeline, and dedicated ATO detection guide ## ATO profile and alert endpoints Account takeover detection now includes dedicated endpoints for querying subject profiles and listing alerts, plus a comprehensive guide covering the full detection workflow. The Anti-Fraud Identity Firewall risk signal pipeline has been expanded from three ingestion paths to four. ### New features * **ATO profile endpoint:** A new [`GET /v1/risk/ato/profile/{subject_id}`](/api-reference/risk/ato-profile) endpoint returns the current risk profile for any subject — including risk level, failed login count, known IP addresses, and known devices. Use this to check a subject's ATO status at any time without triggering a new evaluation. See the [ATO detection guide](/guides/ato-detection#checking-a-subjects-risk-profile). * **ATO alerts endpoint:** A new [`GET /v1/risk/ato/alerts`](/api-reference/risk/ato-alerts) endpoint returns a paginated list of all ATO alerts for your tenant, with cursor-based pagination and optional `subject_id` filtering. Each alert includes the alert type (`velocity_exceeded` or `credential_stuffing`), the risk level when it was triggered, and the `signal_id` linking to the auto-ingested risk signal. See the [ATO detection guide](/guides/ato-detection#listing-alerts). ### Updates * **Four-path risk signal pipeline:** The [risk signals guide](/guides/risk-signals) now documents account takeover detection as a fourth ingestion path alongside direct ingestion, event normalization, and deepfake scanning. All four paths produce the same risk signal records, so you can query signals from any source using the [list signals endpoint](/api-reference/risk-signals/list) or the **Risk & Fraud > Signals** console. See the [updated ingestion path table](/guides/risk-signals#choosing-an-ingestion-path). * **ATO detection guide:** A dedicated [account takeover detection guide](/guides/ato-detection) walks through the full workflow — sending login events, understanding threshold rules and event types, checking subject profiles, listing alerts, and implementing common integration patterns like blocking on elevated risk and combining ATO with event normalization. Includes code examples in cURL, JavaScript, and Python. **Week of June 19, 2027** Account takeover detection with velocity heuristics, automatic alerts, and deepfake scan API improvements ## Account takeover detection The Anti-Fraud Identity Firewall now includes built-in account takeover (ATO) detection. The platform tracks failed login velocity per subject and automatically escalates risk levels when thresholds are exceeded — no external fraud tool required. See the [ATO detection guide](/guides/ato-detection) for the full workflow. ### New features * **ATO risk evaluation endpoint:** A new [`POST /v1/risk/ato/evaluate`](/api-reference/risk/ato-evaluate) endpoint accepts login events and evaluates them against velocity-based heuristics. Each call tracks the subject's failed login count within a rolling one-hour window and returns a risk level — `normal`, `elevated`, `high`, or `critical` — based on configurable thresholds (5, 10, and 20 failed attempts). Use this to assess account takeover risk in real time as login events occur. * **Automatic ATO alerts:** When a subject's failed login count crosses a threshold, the platform automatically creates an alert and ingests a risk signal with `signal_type: "ato"` into your existing [risk signal pipeline](/guides/risk-signals). Alerts at the `elevated` and `high` levels are classified as `velocity_exceeded`; at 20+ failures the alert type escalates to `credential_stuffing`. The response includes the `signal_id` so you can trace the alert back to its corresponding signal in the [Risk & Fraud console](/guides/risk-signals) or via the [list signals endpoint](/api-reference/risk-signals/list). * **ATO subject profiles:** Each evaluated subject gets a profile that tracks their current risk level, failed login count, and known IP addresses. Retrieve a subject's profile via [`GET /v1/risk/ato/profile/{subject_id}`](/api-reference/risk/ato-profile) to check their ATO status at any time without triggering a new evaluation. Query alerts for a subject via the [list ATO alerts endpoint](/api-reference/risk/ato-alerts). ### Updates * **Deepfake scan results API — expanded code examples:** The [scan results retrieval endpoint](/api-reference/risk/deepfake-results) now includes JavaScript and Python examples alongside cURL, making it easier to integrate scan result lookups into your application code. **Week of June 12, 2027** Unified three-path risk signal pipeline and deepfake scan API improvements ## Unified risk signal pipeline and deepfake scan improvements The Anti-Fraud Identity Firewall now officially supports three ingestion paths for creating risk signals, and the deepfake scan API has been refined with additional response data and broader SDK coverage. ### Updates * **Three-path risk signal pipeline:** The [risk signals guide](/guides/risk-signals) now documents deepfake and impersonation scanning as a full third ingestion path alongside direct ingestion and event normalization. All three paths produce the same risk signal records, so you can query and review signals from any source using the [list signals endpoint](/api-reference/risk-signals/list) or the **Risk & Fraud > Signals** console page. See the [ingestion path comparison table](/guides/risk-signals#choosing-an-ingestion-path). * **Deepfake scan API improvements:** The [deepfake scan endpoint](/api-reference/risk/deepfake-scan) now returns additional fields in the response — `detection_model`, `attestation_id`, `created_at`, `subject_ref`, and `subject_type` — giving you richer context for each scan result. The endpoint also includes JavaScript and Python code examples alongside cURL, and documents the pre-computed score passthrough option for teams using external ML models. **Week of June 5, 2027** Deepfake scan results retrieval endpoint and comprehensive detection guide ## Deepfake scan results retrieval You can now look up the latest deepfake and impersonation scan result for any previously scanned subject — without re-running the scan. ### New features * **Scan results retrieval endpoint:** A new [`GET /v1/risk/deepfake/results/{subject_ref}`](/api-reference/risk/deepfake-results) endpoint returns the most recent scan result for a given subject reference. Use it to check the current deepfake and impersonation status of images, videos, documents, attestations, or identities at any time. The response includes the verdict, scores, triggered indicators, and the linked `signal_id` if the scan exceeded the risk threshold. * **Deepfake detection guide:** A dedicated [deepfake and impersonation detection guide](/guides/deepfake-detection) walks through the full workflow end to end — submitting scans, reviewing verdicts, using pre-computed scores, linking scans to attestations, and retrieving results. Includes a complete indicator reference table and code examples in cURL, JavaScript, and Python. **Week of May 29, 2027** Anti-Fraud Identity Firewall now a core platform capability with end-to-end fraud detection ## Anti-Fraud Identity Firewall — now a core platform capability The Anti-Fraud Identity Firewall is now prominently featured as a core use case alongside attestations, content protection, and compliance. All three pillars of the system — risk signal ingestion, identity event normalization, and deepfake/impersonation detection — have documented integration routes. ### Updates * **Anti-fraud promoted to core use case:** The [introduction](/introduction) and [quickstart](/quickstart) pages now feature the Anti-Fraud Identity Firewall alongside existing platform capabilities. New users can discover fraud detection workflows from the moment they land in the docs, with direct links to the [risk signals guide](/guides/risk-signals), the [signal ingestion API](/api-reference/risk/ingest-signal), the [event normalization API](/api-reference/risk/normalize-event), and the [deepfake scan API](/api-reference/risk/deepfake-scan). * **End-to-end fraud detection pipeline:** With this milestone, you can now run a complete fraud detection workflow entirely within Truthlocks — ingest signals from external fraud tools, normalize raw identity events into scored signals automatically, scan subjects for deepfake and impersonation indicators, and review everything in the Risk & Fraud console. See the [risk signals guide](/guides/risk-signals) for a full walkthrough. **Week of May 22, 2027** Deepfake and impersonation detection API, risk signal field standardization, and new event mapping ## Deepfake and impersonation detection You can now scan subjects — images, videos, documents, attestations, and identities — for deepfake and impersonation indicators. Scans that exceed the risk threshold automatically create a [risk signal](/guides/risk-signals), connecting detection directly to the Anti-Fraud Identity Firewall pipeline. This week also includes field standardization across the risk signals API and an additional built-in event mapping. ### New features * **Deepfake and impersonation scan API:** A new [`POST /v1/risk/deepfake/scan`](/api-reference/risk/deepfake-scan) endpoint accepts a subject reference and either raw indicator signals or pre-computed scores from your external models. The platform's heuristic engine maps indicators — face swaps, inconsistent lighting, compression artifacts, biometric mismatches, and identity document discrepancies — to deepfake and impersonation scores on a 0–100 scale. Each scan returns a verdict of `authentic`, `suspect`, `deepfake`, or `impersonation` along with the list of triggered indicators. See the [risk signals guide](/guides/risk-signals). * **Automatic risk signal creation:** When a scan's deepfake or impersonation score reaches 60 or above, the platform automatically ingests a risk signal into your tenant's pipeline — no extra API call needed. The response includes the `signal_id` so you can trace the scan result to its corresponding signal in the [Risk & Fraud console](/guides/risk-signals#console-view) or via the [list signals endpoint](/api-reference/risk-signals/list). * **Pre-computed score passthrough:** If you already have scores from an external ML model or detection service, pass `deepfake_score` and `impersonation_score` directly to skip heuristic analysis. The platform still applies the same verdict thresholds and automatic signal ingestion, so you get consistent classification regardless of the detection source. * **Attestation linking:** Associate any scan with an existing attestation by passing an `attestation_id`. This ties deepfake detection results to the credential they relate to, making it easier to flag and review suspicious attestations. ### Updates * **Standardized field names across the risk signals API:** The signal ingestion and query endpoints now use `subject_type` and `subject_id` consistently, replacing the earlier `entity_type` and `entity_id` field names. If your integration references the old field names, update them to `subject_type` and `subject_id`. The six supported subject types remain the same — `user`, `issuer`, `attestation`, `session`, `ip`, and `device`. See the [signal ingestion endpoint](/api-reference/risk/ingest-signal) and the [list signals endpoint](/api-reference/risk-signals/list). * **New `verification.failed` event mapping:** The [event normalization endpoint](/api-reference/risk/normalize-event) now recognizes `verification.failed` as a built-in event type, mapping it to signal type `behavior` with a base score of 60. This joins the existing five mappings — `login.failed.repeated`, `login.suspicious_geo`, `verification.invalid_sig`, `attestation.deepfake_suspect`, and `session.hijack_suspect` — giving you six pre-calibrated event types out of the box. See the [built-in event mappings table](/guides/risk-signals#built-in-event-mappings). **Week of May 15, 2027** Anti-Fraud Identity Firewall foundation complete — two ingestion paths, six entity types, and a dedicated console ## Anti-Fraud Identity Firewall — foundation complete The risk signal system that began rolling out in late April is now fully available. You have two ways to feed fraud-detection data into Truthlocks, a dedicated console section for reviewing signals, and tenant-isolated storage with production-grade querying. ### Updates * **Two ingestion paths:** Submit pre-scored signals from external fraud tools via [`POST /v1/risk/signals`](/api-reference/risk/ingest-signal), or send raw identity events via [`POST /v1/risk/events`](/api-reference/risk/normalize-event) and let the platform normalize them into scored signals automatically. Use direct ingestion when you already have a risk score; use event normalization for platform-native events like failed logins, suspicious geolocations, and deepfake detections. See the [risk signals guide](/guides/risk-signals). * **Six entity types for signal ingestion:** The signal ingestion endpoint now supports six entity types — `user`, `issuer`, `session`, `device`, `ip`, and `attestation` — so you can attach signals at the right granularity for your use case. Scores use a 0–100 integer scale, with scores at or above 80 triggering automatic review decisions. * **Idempotent signal ingestion:** Pass an `Idempotency-Key` header when ingesting signals to safely retry without creating duplicates. Duplicate signals with the same key are silently ignored. * **Risk & Fraud console:** The **Risk & Fraud > Signals** page in the console lets you browse, filter, and inspect all ingested signals with color-coded score badges. Filter by source, type, or minimum score, and click any row for full details. Cases and Dashboard pages are available in the navigation as the feature set expands. * **Cursor-based pagination and filtering:** The [list signals endpoint](/api-reference/risk-signals/list) supports cursor-based pagination with filters for source, signal type, entity type, entity ID, and minimum score — ready for dashboards, alert pipelines, and batch analysis. **Week of May 8, 2027** Identity event normalization with automatic risk signal creation and metadata enrichment ## Identity event normalization and enrichment You can now submit raw identity events — failed logins, suspicious geolocations, invalid signatures, deepfake detections — and have them automatically converted into standardized [risk signals](/guides/risk-signals) with pre-calibrated scores and enriched metadata. ### New features * **Identity event normalization API:** A new `POST /v1/risk/events` endpoint accepts raw platform events and automatically maps them to canonical risk signal types with base scores. The platform recognizes built-in event types including `login.failed.repeated` (maps to `ato`, score 70), `login.suspicious_geo` (maps to `geo_anomaly`, score 65), `verification.invalid_sig` (maps to `behavior`, score 75), `attestation.deepfake_suspect` (maps to `deepfake`, score 85), and `session.hijack_suspect` (maps to `ato`, score 90). Unknown event types are accepted with a safe fallback so you can start sending events immediately. The response includes both the raw event ID and the normalized signal ID for full traceability. See the [event normalization guide](/guides/risk-signals#event-normalization) and the [API reference](/api-reference/risk/normalize-event). * **Automatic metadata enrichment:** Normalized signals are enriched with available context — issuer trust tier, geolocation, and device metadata — before being stored. This means signals created through event normalization carry richer context than manually ingested signals, improving downstream fraud analysis without extra work on your part. * **Unified signal pipeline:** Events submitted to `/v1/risk/events` produce the same risk signal records as direct ingestion via `/v1/risk/signals`. You can query, filter, and review normalized signals using the existing [list endpoint](/api-reference/risk-signals/list) and the **Risk & Fraud > Signals** console page — no changes to your existing workflows. ### Updates * **Expanded risk signal ingestion fields:** The [signal ingestion endpoint](/api-reference/risk/ingest-signal) now supports `subject_type` for categorizing entities (`user`, `issuer`, `session`, `device`, `ip`, `attestation`), `user_agent` for browser context, and an `Idempotency-Key` header for safe retries — duplicate signals with the same key are silently ignored. Risk scores use a 0–100 integer scale, with scores at or above 80 triggering automatic review decisions. **Week of May 1, 2027** Risk signal entity types, flexible signal taxonomy, and tenant-isolated querying ## Risk signals — entity types, flexible taxonomy, and integration querying The [risk signal ingestion pipeline](/guides/risk-signals) now supports five entity types, free-form signal classification, and tenant-isolated querying with cursor-based pagination — making it ready for production integrations with your fraud-detection stack. ### Updates * **Six subject types:** Each risk signal is tied to one of six subject types — `user`, `issuer`, `attestation`, `session`, `ip`, or `device` — so you can model signals at the right granularity for your use case. For example, attach device fingerprint signals to a `device` subject and IP reputation scores to an `ip` subject, then query signals for a specific subject across all sources. See the [ingest endpoint](/api-reference/risk-signals/ingest). * **Flexible signal taxonomy:** The `source` and `signal_type` fields are free-form strings, so you can define your own naming conventions across integrations — `device_fingerprint`, `ip_reputation`, `email_verification`, `behavioral`, or any custom source. This lets you centralize signals from multiple vendors without mapping to a fixed schema. See the [risk signals guide](/guides/risk-signals). * **Tenant-isolated signal storage:** All risk signals are protected by [row-level security](/security/rls). Signals are bound to your tenant at ingestion time and queries can only return your own signals — ensuring complete data isolation in multi-tenant deployments. * **Cursor-based pagination and filtering:** The [list signals endpoint](/api-reference/risk-signals/list) supports cursor-based pagination with filters for `source`, `signal_type`, `subject_type`, `subject_id`, and `min_score`. Use this to build dashboards, alert pipelines, or batch analysis jobs against your ingested signal data. **Week of April 24, 2027** Risk signal ingestion API, Risk & Fraud console, and signal filtering ## Risk signal ingestion pipeline A new risk signal system for ingesting, viewing, and filtering fraud and abuse signals — the foundation of the upcoming Anti-Fraud Identity Firewall. ### New features * **Risk signal ingestion API:** You can now submit risk signals to the platform via `POST /v1/risk/signals` and retrieve them individually via `GET /v1/risk/signals/{id}` or as a filtered, paginated list via `GET /v1/risk/signals`. Each signal carries a risk score (0–1), source identifier, and signal type, giving you a structured way to feed fraud and abuse intelligence into your verification workflows. Use this to centralize risk data from third-party fraud tools, manual reviews, or internal detection systems. * **Risk & Fraud console section:** A new **Risk & Fraud** section in the console provides a dedicated Signals page where you can browse all ingested risk signals with color-coded score badges (green for low, amber for medium, red for high), filter by source, type, or minimum score, and paginate through results. Cases and Dashboard pages are also available in the navigation as the feature set expands in the coming weeks. **Week of April 17, 2027** Console login fix for Business tenants and security hardening ## Console login fix and security hardening A critical fix for Business tenant console access and two security improvements to the platform's browser and API protections. ### Updates * **Console security hardening:** The console's Content Security Policy now blocks inline script evaluation, closing a potential cross-site scripting vector. No action is needed on your part — this change is applied automatically. * **Shorter CORS preflight cache:** The API gateway now caches CORS preflight responses for one hour instead of 24 hours. If you update your integration's origin or headers, the change takes effect faster without waiting for the previous cache window to expire. ### Bug fixes * **Console login fix for Business tenants:** All Business-tier tenants were unable to log in to the console due to an account routing issue. The issue has been resolved and affected accounts have been automatically repaired — you can now log in normally. **Week of April 10, 2027** Console receipt management, export endpoint change, and stability fix ## Console receipt management and receipt export endpoint change The console now supports the full receipts workflow — search, export, proof bundle download, and redaction — and the receipt export status endpoint has moved to a new path. ### Updates * **Console receipt management:** The Receipts page in the console now includes search, export, proof bundle download, and redaction controls. Search receipts by keyword or filter directly from the list view. Export receipts as CSV or JSON with a status banner that tracks job progress. Download a self-contained proof bundle from any receipt's detail page. Redact a receipt's payload with a confirmation dialog (active receipts only). These features were previously only available via the API — they are now fully accessible from the console. See the [receipts guide](/guides/receipts). * **Receipt export status endpoint moved:** The endpoint for checking a receipt export job's status has moved from `GET /v1/receipts/export/{id}` to `GET /v1/receipt-exports/{id}`. If you poll for export completion in your integration, update the URL to use the new path. The `POST /v1/receipts/export` endpoint for queuing exports is unchanged. See [receipt export](/api-reference/receipts/export). ### Bug fixes * **Server stability fix:** A routing conflict could cause the service to crash on startup under certain conditions. The conflict has been resolved — no action is needed on your part. **Week of April 1, 2027** Truth Receipts — signed event receipts with custom types, verification, search, export, and redaction ## Truth Receipts A new receipt system for creating cryptographically signed, transparency-log-anchored records of discrete events — payments, security incidents, compliance checks, deliveries, and more. This release also adds custom receipt types, per-type signing policies, independent receipt verification, full-text search, bulk export, and GDPR-ready redaction. ### New features * **Truth Receipts:** You can now mint signed, immutable receipts for any event type. Each receipt is cryptographically signed with your issuer key (Ed25519 or ES256), anchored in the transparency log with a Merkle inclusion proof, and offline-verifiable via proof bundle export. Use receipts to create tamper-evident records of payments, security events, document deliveries, compliance checks, or any custom event. See the [receipts guide](/guides/receipts). * **Five platform receipt types:** Five receipt types are available out of the box — `payment_receipt` for payments and refunds, `security_event_receipt` for auth events and key rotations, `delivery_receipt` for document deliveries and notifications, `compliance_receipt` for KYC/AML checks and regulatory evidence, and `custom_receipt` for any other event. Each type includes a JSON Schema that validates your payload before signing. See [receipt types](/api-reference/receipts/list-types). * **Custom receipt types:** Create your own receipt types with custom JSON Schemas via `POST /v1/receipt-types`. Deprecate or archive types you no longer need. Use this to model domain-specific events — warranty claims, inspection reports, delivery confirmations — with schema-validated payloads. See [create a receipt type](/api-reference/receipts/create-type). * **Signing policies:** Define per-type signing policies that control which issuers, trust tiers, and signing algorithms are allowed. For example, restrict `compliance_receipt` to HSM-backed keys from issuers with a minimum trust tier. See [signing policies](/api-reference/receipts/signing-policy). * **Receipt verification:** Verify any receipt independently via `POST /v1/receipts/verify`. The endpoint checks revocation status, key compromise history, and cryptographic signature validity, returning one of six verdicts — `VALID`, `REVOKED`, `INVALID_SIGNATURE`, `KEY_COMPROMISED`, `KEY_INACTIVE`, or `NOT_FOUND`. See [receipt verification](/api-reference/receipts/verify). * **Receipt proof bundles:** Download a self-contained proof bundle for any receipt via `GET /v1/receipts/{id}/proof-bundle`. The bundle includes the signed receipt envelope, Merkle inclusion proof, and issuer key snapshot — everything needed for offline verification. See [proof bundles](/api-reference/receipts/proof-bundle). * **Receipt search:** Search across receipts using full-text queries and faceted filters — by type, status, issuer, date range, or indexed payload fields. See [receipt search](/api-reference/receipts/search). * **Receipt export:** Queue asynchronous bulk exports of receipts as JSON or CSV. Poll for completion and download from a pre-signed URL. See [receipt export](/api-reference/receipts/export). * **Receipt redaction:** Permanently remove PII from a receipt's payload while preserving the cryptographic proof, transparency log entry, and Merkle inclusion proof. A `RECEIPT_REDACT` event is anchored in the log for auditability. Use this for GDPR right-to-erasure requests. See [receipt redaction](/api-reference/receipts/redact). * **Receipts API:** Manage receipts programmatically — mint (`POST /v1/receipts`), list with filters (`GET /v1/receipts`), retrieve by ID (`GET /v1/receipts/{id}`), and revoke (`POST /v1/receipts/{id}/revoke`). Mint and revoke require idempotency keys; check each operation contract. See the [receipts API reference](/api-reference/receipts/mint). * **Receipts in the console:** A new Receipts page in the console lets you browse, search, and filter receipts by type and status. Click any receipt to view its full detail page, including the cryptographic signature and transparency log anchor. A separate Receipt Types page lets you manage custom types and view signing policies. * **SDK support:** The JavaScript, Go, and Python SDKs now include a full `receipts` resource — mint, list, get, revoke, verify, search, export, redact, proof bundle download, and type management. See [SDK examples](/guides/receipts#sdk-examples). * **Receipt webhook events:** Subscribe to `receipt.created`, `receipt.revoked`, `receipt.type.created`, and `receipt.type.deprecated` events via your existing [webhook endpoints](/guides/webhooks) to react to receipt activity in real time. * **Retention policies:** Set a retention policy when minting a receipt — `standard` (2 years), `extended` (7 years), or `permanent` — to control how long receipt data is retained. Expired receipts are cleaned up automatically. See [retention policy](/guides/receipts#retention-policy). ### Bug fixes * Fixed a login issue where newly verified tenants were blocked from signing in. If you verified your email but couldn't log in, this has been resolved — your account is now activated automatically upon email verification. * Fixed a server error that could occur when listing receipts under certain conditions, improving reliability of the [receipts API](/api-reference/receipts/list). * Fixed an incorrect icon on the Receipts navigation item in the console that displayed a fallback instead of the intended icon. **Week of February 2, 2027** Production readiness milestone, tenant lifecycle improvements, and security hardening ## Production readiness milestone, tenant lifecycle improvements, and security hardening The platform has completed its full enterprise readiness verification. All production deployment gates — security, tenant isolation, load testing, and infrastructure hardening — have passed. ### Updates * **Signing key security enforcement:** All attestation signing in production now uses KMS-backed keys exclusively. Development keystores are blocked from running in production and staging environments, ensuring every signature is backed by hardware-grade key protection. * **Tenant isolation hardening:** Row-level security policies have been standardized across all services, closing edge cases where tenant data boundaries could be inconsistent. CI gates now prevent regressions, so every release is verified for tenant isolation before deployment. * **API contract verification:** A new automated check validates that the OpenAPI specification matches live API handlers on every release. This prevents drift between the [API reference](/api-reference/attestations/mint) and actual API behavior, so the documentation you read always reflects what the API does. * **Gateway route parity:** Development and production API gateways are now verified to serve identical route surfaces, eliminating environment-specific routing differences that could cause unexpected behavior when moving from sandbox to production. See [environments](/environments). * **DDoS and bot protection:** Production endpoints are now protected by WAF rules and bot defenses at the edge, adding a layer of protection in front of existing [rate limits](/ops/limits) and [abuse hardening](/security/abuse-hardening). **Week of January 12, 2027** Dunning contract modes, add-on price transparency, and expanded regional pricing ## Dunning contract modes, add-on price transparency, and expanded regional pricing More granular billing admin controls, transparent add-on pricing, and broader regional coverage. ### Updates * **Add-on price transparency:** The add-ons catalog now displays base prices for all seven add-ons — from $25/seat/month for Extra Seats to $499/month for Private Log — so you can compare costs before attaching an add-on. See [add-ons](/billing/overview#add-ons). * **Expanded Tier 1 regional pricing:** Ten additional countries have been added to the Tier 1 pricing region — Netherlands, Switzerland, Ireland, Italy, Spain, Sweden, Norway, Denmark, Finland, and New Zealand — so tenants in these markets now pay the standard base price for add-ons. See [regional add-on pricing](/billing/overview#regional-add-on-pricing). **Week of December 29, 2026** Blog launch, help center, and SEO improvements across all public apps ## Blog launch, help center, and SEO improvements A public blog with 12 launch articles, a centralized help center, and better search engine discoverability across the platform. ### New features * **Blog:** The [marketing site](https://www.truthlocks.com/blog) now includes a blog with 12 articles across six categories — Product, Security, Engineering, Company, Developer, and Partnerships. Each post includes structured data for rich search snippets, cover images, and newsletter signup. Filter by category to find topics relevant to you. * **Help center:** A new [help page](https://www.truthlocks.com/help) organizes support resources into four sections — Getting Started, Developers, Creators, and Enterprise — with direct links to guides, API docs, and contact options so you can find answers faster. ### Updates * **SEO improvements:** All public-facing apps — marketing site, docs, verify portal, status page, and transparency log — now include canonical URLs, Open Graph tags, Twitter cards, JSON-LD structured data, and sitemaps. Pages render richer previews when shared on social media or indexed by search engines. * **Marketing page accuracy:** Several marketing pages have been updated to align more closely with current platform capabilities. * **Non-www redirect:** Requests to `truthlocks.com` now automatically redirect to `www.truthlocks.com` for consistent URLs across search indexing and link sharing. ### Bug fixes * Fixed an incorrect social media link that pointed to the wrong X (Twitter) account. **Week of December 22, 2026** Billing self-service APIs for plans, rates, cost estimation, and subscription management ## Billing self-service APIs Seven new billing API endpoints give you programmatic control over plan selection, cost forecasting, and subscription management. ### New features * **Plan catalog API:** Browse all available subscription tiers — including pricing, features, and quotas — via `GET /v1/billing/plans`. Use this to build custom pricing pages or let users compare plans before subscribing. No authentication required. See [list plans](/api-reference/billing/plans). * **Per-use rate lookup:** Check your tenant's effective per-mint and per-verification rates, including any custom rate card or regional pricing adjustments, via `GET /v1/billing/rates`. See [get rates](/api-reference/billing/rates). * **Plan cost estimator:** Submit your expected usage to `POST /v1/billing/estimate` and receive a plan recommendation with estimated monthly cost — useful for onboarding flows and pricing calculators. No authentication required. See [estimate plan cost](/api-reference/billing/estimate). * **Projected invoice calculator:** Get a line-item invoice breakdown for any combination of mints, verifications, and plan via `POST /v1/billing/projected-invoice`. Regional pricing adjustments are applied automatically when you include a country code. See [projected invoice](/api-reference/billing/projected-invoice). * **Subscription cancellation API:** Cancel your subscription via `POST /v1/billing/cancel`. Access continues through the end of your current billing period, then downgrades to the Developer (free) plan. See [cancel subscription](/api-reference/billing/cancel). * **Billing portal sessions:** Redirect users to their payment provider's self-service portal (Stripe, Paystack, or Flutterwave) via `POST /v1/billing/portal` to update payment methods, view invoices, and manage subscriptions. See [create portal session](/api-reference/billing/portal). * **Add-on management API:** Attach and detach add-ons — extra seats, priority SLA, private log, compliance pack, white-label branding, rate limit boost, and extended retention — via the [add-ons endpoints](/api-reference/billing/addons). Free add-ons activate immediately; paid add-ons return a checkout URL. **Week of September 22, 2026** Verify portal dark mode, redesigned navigation, four badge styles, and refreshed UI across all consumer pages ## Verify portal dark mode, redesigned navigation, and four badge styles The verify portal now supports full dark mode, a redesigned collapsible sidebar, four embeddable badge styles, and a visual refresh across every consumer page. ### New features * **Dark mode:** The verify portal now supports dark mode across all consumer pages. Switch between light, dark, and system appearance modes from the toggle in the top bar. Your preference persists across sessions. See the [consumer portal guide](/guides/consumer-portal#dark-mode). * **Four badge styles:** Embeddable verification badges are now available in four styles — default, flat, large, and minimal — each with a dark theme variant. Use `large` on landing pages to show the protection date and content title, or `minimal` for inline text and README footers. See [embeddable badges](/guides/badges#badge-styles). * **Redesigned protection certificates:** Downloaded protection certificates now feature a premium SVG design with a dark header, circular seal, and corner ornaments — suitable for legal evidence, portfolio displays, or print. See [embeddable badges](/guides/badges). ### Updates * **Redesigned sidebar navigation:** The verify portal navigation has been rebuilt as a collapsible rail — a narrow 64 px icon strip that expands on hover to show labels. Pin it open if you prefer a persistent sidebar. On mobile, navigation opens as a slide-out drawer from the hamburger menu. See the [consumer portal guide](/guides/consumer-portal#navigation). * **UI refresh across all consumer pages:** Every page in the verify portal — Dashboard, Protections, Inbox, History, Saved, Profile, Privacy, Security, Billing, and Settings — now features improved loading skeletons, richer card layouts, and a consistent visual language. Protections adds search and sort controls, and the Settings hub uses a card grid with animated navigation. **Week of August 11, 2026** JS and Python SDK idempotency prefix support ## JS and Python SDK idempotency prefix support The JavaScript/TypeScript and Python SDKs now support the idempotency prefix configuration option, matching the Go SDK. ### New features * **JS/TS SDK idempotency prefix:** Set `idempotencyPrefix` when initializing the [JavaScript SDK](/sdk/js) to namespace auto-generated idempotency keys across services sharing the same tenant. See the [idempotency keys section](/sdk/js#idempotency-keys) for a multi-service example. * **Python SDK idempotency prefix:** Set `idempotency_prefix` when initializing the [Python SDK](/sdk/python) to namespace auto-generated idempotency keys. The retry behavior section now includes a callout linking to idempotency key configuration. See the [idempotency keys section](/sdk/python#idempotency-keys) for details. **Week of July 28, 2026** Go SDK idempotency prefix, accounting export improvements, and portal fixes ## Go SDK idempotency prefix, accounting export improvements, and portal fixes A new SDK configuration option for namespacing idempotency keys, a more flexible accounting export endpoint, and reliability fixes across the verify portal and Truth Explorer. ### New features * **Go SDK idempotency prefix:** Set a custom prefix with the new `IdempotencyPrefix` config option when initializing the [Go SDK](/sdk/go) to namespace auto-generated idempotency keys across services — useful when multiple applications share the same tenant. ### Updates * **Accounting export improvements:** The [accounting export endpoint](/api-reference/billing/invoices) now defaults to CSV format and accepts simplified date range parameters (`from` and `to` in `YYYY-MM-DD` format). If no date range is provided, the export covers the last 30 days. See [billing](/billing/overview). * **Simplified username claim response:** The [username claim endpoint](/api-reference/consumer/profile) now returns a streamlined response with just the `status` and `username` fields. Your [portfolio](/guides/portfolio) URL is derived from your username at `verify.truthlocks.com/portfolio/{username}`. ### Bug fixes * The verify portal navigation hamburger menu now opens and closes correctly on mobile. * [Truth Explorer](https://transparency.truthlocks.com) now displays error messages when checkpoint data fails to load, instead of showing a blank "No checkpoints" state. **Week of July 21, 2026** Typed SDK errors, automatic idempotency keys, bearer token auth, and smarter retry behavior ## Typed SDK errors, automatic idempotency keys, and smarter retry behavior All three SDKs now ship structured error classes, automatic idempotency keys for safe retries, and smarter rate-limit handling — making integrations more robust with less code. ### New features * **Typed error handling in all SDKs:** Every API error now returns a structured error object with the HTTP status, machine-readable error code, and human-readable message. The [Go SDK](/sdk/go) adds `.IsCode()` and `.NotFoundError()` helpers for concise error branching. The [Python SDK](/sdk/python) exports a `NotFoundError` subclass you can catch directly. See the error handling section on each SDK page. * **Automatic idempotency keys:** The [JavaScript](/sdk/js) and [Go](/sdk/go) SDKs now generate `Idempotency-Key` headers automatically on write operations like mint and revoke, making retries safe by default. Set a custom prefix with the `idempotencyPrefix` config option to namespace keys across services. * **Bearer token authentication:** The [JavaScript SDK](/sdk/js) now supports session-based JWT authentication alongside API keys and service keys — useful for frontend apps and OAuth-based login flows where a short-lived token is already available. See [authentication](/security/auth). ### Updates * **Retry-After header support:** All three SDKs — [JavaScript](/sdk/js), [Go](/sdk/go), and [Python](/sdk/python) — now honor the `Retry-After` header on HTTP 429 responses, waiting exactly as long as the server specifies instead of relying solely on exponential backoff. This prevents unnecessary retries when you hit a rate limit. * **Configurable request timeouts:** Set a custom timeout when initializing any SDK — milliseconds in [JavaScript](/sdk/js), `time.Duration` in [Go](/sdk/go), or seconds in [Python](/sdk/python). The default is 30 seconds across all three. * **Disable automatic retries:** Set `maxRetries` (or `max_retries` in Python) to `0` to turn off built-in retries entirely — useful when you have your own retry logic or need deterministic failure behavior. See the retry configuration section on each [SDK page](/sdk/js). * **Email delivery on mint:** Pass a `recipient_email` when minting an attestation to deliver the credential directly to the recipient's inbox. Available in all three SDKs and in the [batch minting](/guides/sdk-examples) examples. * **Custom HTTP client in Go:** Inject your own `*http.Client` when initializing the [Go SDK](/sdk/go) to configure custom TLS, proxies, or connection pooling for enterprise environments. **Week of July 14, 2026** Key compromise reporting, service key auth, webhook signature verification, and SDK quality-of-life improvements ## Key compromise reporting, service key auth, and webhook signature verification Report compromised signing keys directly from your SDK, authenticate machine-to-machine workloads with service keys, and verify incoming webhook signatures with a single function call. ### New features * **Key compromise reporting:** If a signing key is compromised, report it immediately from the [JavaScript](/sdk/js) or [Go](/sdk/go) SDK to flag the key and block further signing — protecting existing attestations while you rotate to a new key. See the [key compromise endpoint](/api-reference/issuers/keys-compromise). * **Service key authentication:** A new `tl_svc_` service key type lets you authenticate server-to-server workloads without a user session. Ideal for background jobs, CI/CD pipelines, and microservice integrations. See the [JavaScript SDK](/sdk/js). * **Webhook signature verification helper:** The JavaScript SDK now includes a `verifyWebhookSignature()` utility that validates incoming webhook payloads against the `x-truthlocks-signature` header in a single call. See the [SDK examples](/guides/sdk-examples) page for a complete handler. ### Updates * **Proof bundle download in all SDKs:** All three SDKs — [JavaScript](/sdk/js), [Go](/sdk/go), and [Python](/sdk/python) — now include a dedicated method to download the proof bundle for any attestation. Previously you needed a direct API call. See the [proof bundle spec](/specification/proof-bundle). * **API key management in JavaScript and Go SDKs:** The [JavaScript](/sdk/js) and [Go](/sdk/go) SDKs now support listing, creating, and revoking API keys programmatically. See the [API keys endpoints](/api-reference/api-keys/list). * **Direct issuer suspend and revoke in SDKs:** The [JavaScript](/sdk/js) and [Go](/sdk/go) SDKs now expose direct suspend and revoke methods for cases where you need to act immediately without a [governance workflow](/api-reference/governance/list-requests). * **Python context manager:** The [Python SDK](/sdk/python) now supports Python's `with` statement for automatic HTTP connection cleanup — useful for scripts and short-lived processes. * **Python environment switching:** Pass `environment="sandbox"` when initializing the [Python SDK](/sdk/python) to target the sandbox API without changing the base URL manually. See [environments](/environments). * **Verification result caching pattern:** The [SDK examples](/guides/sdk-examples) page now includes a recommended caching pattern that stores valid results for five minutes while always checking revoked and superseded verdicts fresh — reducing API calls without sacrificing safety. **Week of July 7, 2026** Audit query and governance workflow SDK examples in all three languages ## Audit query and governance workflow SDK examples in all three languages Complete, integration code patterns for querying audit logs and managing governance workflows are now available in every SDK. ### Updates * **Audit query SDK examples:** The [JavaScript](/sdk/js), [Go](/sdk/go), and [Python](/sdk/python) SDKs now include full audit query examples — filter events by resource type, actor, action, or time range, and export compliance reports as CSV. Copy-paste-ready patterns are also available on the [SDK examples](/guides/sdk-examples) page. * **Governance workflow SDK examples:** All three SDKs now include end-to-end governance workflow examples covering the full lifecycle — create a request, collect approvals, and execute — with code for listing pending requests. See the [SDK examples](/guides/sdk-examples) page and individual SDK references for details. **Week of June 30, 2026** Full SDK governance parity, SIEM configuration API, batch minting in Go and Python ## Full SDK governance parity, SIEM configuration API, and batch minting in Go and Python All three SDKs now cover governance and audit workflows, you can configure SIEM streaming destinations via the API, and batch minting examples are available in every language. ### New features * **JS and Python SDK governance and audit methods:** The [JavaScript](/sdk/js) and [Python](/sdk/python) SDKs now include full governance workflow support — create, approve, and execute governance requests, plus query and export audit logs — matching the [Go SDK](/sdk/go). All three SDKs now have identical coverage for [governance workflows](/api-reference/governance/list-requests) and [audit queries](/api-reference/audit/query). * **SIEM streaming configuration API:** Configure real-time audit log streaming to Splunk, Datadog, AWS CloudWatch, Elastic/ELK, or a custom webhook endpoint via the API. Events are buffered and retried automatically if your destination is unreachable. Enterprise tier only. See [audit logs](/security/audit). * **Batch minting in Go and Python:** The [SDK examples](/guides/sdk-examples) page now includes batch minting patterns in Go and Python with configurable concurrency and per-recipient success/failure reporting — matching the existing TypeScript example. ### Updates * **Superseded verdict version chain:** The [verify endpoint](/api-reference/verify) now returns a `superseded_by_attestation_id` field when a credential has been replaced, so you can follow the version chain to the latest attestation in a single step. **Week of June 23, 2026** Username claiming, protection visibility, key rotation, accounting exports ## Username claiming, protection visibility, key rotation, and accounting exports Claim a unique username for your public portfolio, control which protections are visible, rotate signing keys without downtime, and export invoices for accounting. ### New features * **Username claiming:** Claim a globally unique username to activate your public portfolio page at `verify.truthlocks.com/portfolio/{username}`. Your portfolio displays your display name and all public protections with titles, categories, and verification counts. See the [portfolio guide](/guides/portfolio). * **Protection visibility toggle:** Set any content protection to `public` or `private` from the verify portal. Public protections appear on your portfolio and in [similarity searches](/api-reference/consumer/similarity). Private protections are only visible to you. See the [visibility endpoint](/api-reference/consumer/update-visibility). * **Signing key rotation:** Rotate an issuer signing key without revoking it. The old key is marked as `rotated` and remains valid for verifying existing attestations, while the new key becomes active for all future signing. See the [key rotation endpoint](/api-reference/issuers/keys-rotate). * **Accounting export:** Enterprise tenants can export their invoice history as CSV or JSON over a configurable date range. Exports include invoice number, status, dates, amounts, tax, and PO references — everything needed for reconciliation. See [billing](/billing/overview). * **Asset upload API:** Upload files up to 5 MB via the API. Assets are stored with AES-256 encryption and served with proper content-type headers and caching. Useful for logos, evidence files, and supporting documentation. ### Updates * **Platform broadcast announcements:** Announcements from Truthlocks — including system updates, security alerts, and operational notifications — now appear directly in your console inbox with priority levels (normal, urgent, critical). See the [announcements endpoints](/api-reference/announcements/list). * **Key rotation reminders:** The platform now warns you when signing keys approach 90 days old and webhook secrets approach 180 days old, so you can rotate them before they become a compliance risk. See the [webhooks guide](/guides/webhooks). **Week of June 9, 2026** Interactive API playground on every endpoint, full three-language SDK parity ## Interactive API playground on every endpoint and full SDK parity The API reference is now fully interactive, and all three SDKs have identical workflow coverage. ### Updates * **Interactive API playground on every endpoint:** All 50+ [API reference](/api-reference/attestations/mint) endpoints now support the interactive playground with pre-filled parameters and one-click environment switching between [Production and Sandbox](/environments). You can test any request directly from the docs without leaving the page. * **Full three-language SDK parity:** The [JavaScript](/sdk/js), [Go](/sdk/go), and [Python](/sdk/python) SDKs now have identical workflow coverage — including credential issuance, verification, revocation, and supersede. Every [SDK example](/guides/sdk-examples) is available in all three languages with copy-paste-ready code. * **Sandbox environment in the API playground:** Switch between Production (`api.truthlocks.com`) and Sandbox (`sandbox-api.truthlocks.com`) directly in the API playground on any endpoint page. Sandbox requests use isolated test data so you can experiment safely. See [environments](/environments). **Week of June 2, 2026** Request examples across the API reference, complete Python coverage in all SDK workflows ## Request examples across the API reference and complete Python coverage Every API endpoint now includes copy-paste request examples, and Python coverage is complete across all SDK workflows and reference pages. ### Updates * **Request examples on every API endpoint:** All [API reference](/api-reference/attestations/mint) endpoints now include ready-to-use request examples in cURL, JavaScript, and Python. You can copy a working request directly from any endpoint page — including [attestations](/api-reference/attestations/list), [governance](/api-reference/governance/approve), [consumer](/api-reference/consumer/inbox), [issuers](/api-reference/issuers/create), and [audit](/api-reference/audit/query) — and start integrating immediately. * **Complete Python SDK workflow coverage:** The [SDK examples](/guides/sdk-examples) page now includes Python code for every section, including end-to-end credential issuance, document attestation with SHA-256 hashing, and revoke-and-supersede workflows. Combined with the new request examples above, Python developers now have the same first-class integration experience as TypeScript and Go. * **Revoke examples on all SDK pages:** The [JavaScript](/sdk/js), [Go](/sdk/go), and [Python](/sdk/python) SDK reference pages each include a dedicated "Revoke an attestation" section with a complete code example, making credential lifecycle management easier to implement. **Week of May 26, 2026** Full Python SDK parity, revoke examples on every SDK page ## Full Python SDK parity and revoke examples on every SDK page Python examples now cover every workflow in the SDK docs, and all three SDK reference pages include dedicated revoke sections. ### Updates * **Full Python SDK parity:** The [SDK examples](/guides/sdk-examples) page now includes Python code for every section — end-to-end credential issuance and verification, document attestation with SHA-256 hashing, and revoke-and-supersede workflows. Python developers get the same copy-paste-ready patterns already available in TypeScript and Go. * **Revoke examples on all SDK pages:** The [JavaScript](/sdk/js), [Go](/sdk/go), and [Python](/sdk/python) SDK reference pages now each include a dedicated "Revoke an attestation" section with a complete code example, matching the existing supersede sections. * **Clearer policy evaluate response docs:** The [issuance policies guide](/guides/issuance-policies) now explicitly notes that `evaluation_ms` has been removed from the [evaluate endpoint](/api-reference/policies/evaluate) response and points you to the [decision audit trail](/security/audit#policy-decision-audit-trail) for performance data. **Week of May 19, 2026** Revoke and supersede SDK examples, Python SDK references ## Revoke and supersede SDK examples and Python SDK references New integration code patterns for credential lifecycle management and broader SDK coverage across the developer docs. ### Updates * **Revoke and supersede SDK examples:** The [SDK examples](/guides/sdk-examples) page now includes full TypeScript and Go patterns for [revoking](/api-reference/attestations/revoke) an attestation and [superseding](/api-reference/attestations/supersede) it with an updated version. Each example covers the complete workflow — revocation with a reason, post-revocation verification, and supersede with a new payload — so you can integrate credential lifecycle management without guesswork. * **Python SDK references:** The [SDK examples](/guides/sdk-examples) page and all related quick-links now reference the [Python SDK](/sdk/python) alongside JavaScript and Go, making it easier to find the right SDK for your stack. **Week of May 12, 2026** Simplified policy evaluate response, CSV exports for all frameworks, new developer guides ## Simplified policy evaluate response, CSV exports for all frameworks, and new developer guides A leaner policy evaluate response, full CSV support for every compliance framework, and new guides for SDK workflows, data residency, and support access. ### Updates * **Simplified policy evaluate response:** The [evaluate endpoint](/api-reference/policies/evaluate) no longer returns `evaluation_ms`. The `reasons` field is now only populated when a request is denied, giving you a cleaner response to parse. If you were using `evaluation_ms` for performance monitoring, query `resource_type=policy_decision` in the [decision audit trail](/security/audit#policy-decision-audit-trail) instead. * **CSV export for all compliance frameworks:** [Compliance exports](/guides/compliance-exports#export-formats) now support CSV output for SOC 2 and GDPR in addition to HIPAA. Pass `format=csv` with any `report_type` to the [audit export endpoint](/api-reference/audit/export). * **SDK examples guide:** A new [SDK examples](/guides/sdk-examples) page provides integration code patterns for common workflows — minting and verifying attestations, revoking and superseding credentials, validating webhook signatures, and more. Examples are available in TypeScript and Go. * **Data residency guide:** A dedicated [data residency](/security/data-residency) guide explains how to pin tenant data to a specific region (US, EU, or Africa), what stays in-region, and how cross-region requests are handled. * **Support access documentation:** New documentation explains how support staff access your tenant through [time-limited impersonation sessions](/security/support-access) with scoped permissions, automatic expiry, and full audit logging. * **Policies API request examples:** The [create policy](/api-reference/policies/create) and [evaluate policy](/api-reference/policies/evaluate) endpoints now include complete curl examples and accurate response field descriptions. **Week of May 5, 2026** Policies API, issuer applications API, custom roles API, framework-specific exports ## Policies API, issuer applications API, custom roles API, and framework-specific exports Manage issuance policies, submit issuer applications, create custom roles, and target compliance exports to a specific framework — all programmatically through new API endpoints. ### New features * **Policies API:** Create, list, simulate, and delete [issuance policies](/guides/issuance-policies) through the API. Test how a policy evaluates a given request with the [evaluate endpoint](/api-reference/policies/evaluate) before enforcing it. See the full [policies API reference](/api-reference/policies/create). * **Issuer applications API:** Submit issuer applications, upload supporting evidence, and track application status through the API instead of the console. See the [issuer applications API reference](/api-reference/issuer-applications/create) and the [issuer applications guide](/guides/issuer-applications). * **Custom roles API:** Create custom roles and assign them to users programmatically. Define access permissions tailored to your team and assign them through the [create role](/api-reference/identity/create-role) and [assign role](/api-reference/identity/assign-role) endpoints. See [RBAC & permissions](/security/rbac). * **Announcements API:** Retrieve and manage platform announcements — system updates, security alerts, and operational notifications — through the [announcements endpoints](/api-reference/announcements/list). * **Framework-targeted audit exports:** The [audit export endpoint](/api-reference/audit/export) now accepts an optional `report_type` parameter (`soc2`, `gdpr`, or `hipaa`) so you can generate a framework-specific report in a single request. Omit the parameter to get a raw audit log export. Requires the Compliance Pack add-on. See the [compliance exports guide](/guides/compliance-exports). * **Policy bindings API:** A new `/v1/policies/bindings` endpoint lets you bind a policy to an individual issuer, a verification profile, or the tenant default — each with a priority value. The highest-priority binding is evaluated first and the first `DENY` stops evaluation. See [policy bindings](/guides/issuance-policies#policy-bindings). ### Updates * **Policy decisions in audit logs:** Policy evaluation records are now queryable as standard audit events. Filter by `resource_type=policy_decision` and the `decision_id` returned from the evaluate endpoint to trace exactly which policy version, rules, and input hash applied. See [decision audit trail](/security/audit#policy-decision-audit-trail). * **CSV export for all frameworks:** Compliance exports now support CSV output for all report types (SOC 2, GDPR, and HIPAA), not just HIPAA. See the [compliance exports guide](/guides/compliance-exports#export-formats). **Week of April 28, 2026** Compliance exports, policy bindings, decision audit trail ## Compliance exports, policy bindings, and decision audit trail Export audit data in SOC 2, GDPR, and HIPAA formats, bind policies to specific targets, and trace every policy decision through a queryable audit trail. ### New features * **Compliance exports:** Export audit data formatted for SOC 2, GDPR, and HIPAA compliance reviews from **Settings > Audit > Export** or via the API. Each export runs as a background job with downloadable JSON and CSV output. See the [compliance exports guide](/guides/compliance-exports). * **Policy bindings:** Bind issuance policies to specific targets — an individual issuer, a verification profile, or the tenant default — with priority-ordered evaluation so the most specific policy wins. See [issuance policies](/guides/issuance-policies). * **Decision audit trail:** Every policy evaluation now records a `decision_id`, the policy version, matched rules, and a SHA-256 hash of the input. Query past decisions through the [audit events API](/api-reference/audit/query) for full traceability. * **Condition operators and fields reference:** Seven operators (`eq`, `neq`, `in`, `nin`, `gt`, `lt`, `exists`) and eight evaluation fields with dot-notation support give you fine-grained control over [issuance policy rules](/guides/issuance-policies). ### Updates * **Enterprise branding API:** Manage brand assets programmatically — retrieve and update branding settings, upload logos via a presigned URL flow, and configure colors. Plan-gated to Business and Enterprise tiers. See the [enterprise branding guide](/guides/enterprise-branding). * **Compliance review workflow:** A dedicated guide now walks through the full four-stage review lifecycle — Requested, In Progress, Submitted, and Reviewed — including evidence attachments, reviewer outcomes, and email notifications at each step. See the [compliance review guide](/guides/compliance-review). **Week of April 21, 2026** Consumer settings, pricing calculator, public proof metadata API ## Consumer settings, pricing calculator, and public proof metadata API New self-service settings for consumers on the verify portal, a pricing calculator with regional rates, and a public API for proof page metadata. ### New features * **Consumer language and region preferences:** Choose your display language and preferred data residency region from **Settings > Language & Region** on the [verify portal](https://verify.truthlocks.com). Five languages and seven regions are available at launch. See the [consumer portal guide](/guides/consumer-portal). * **Connected apps management:** View and revoke third-party applications that have access to your account from **Settings > Connected Apps** on the [verify portal](https://verify.truthlocks.com). Each entry shows the app's granted permissions and when access was authorized. See the [consumer portal guide](/guides/consumer-portal). * **Notification preferences:** Control which emails and push notifications you receive — verification alerts, security alerts, marketing updates, and more — from **Settings > Notifications** on the [verify portal](https://verify.truthlocks.com). See the [consumer portal guide](/guides/consumer-portal). * **Device management:** View all devices linked to your account with verification status and last-active timestamps. Remove devices you no longer use from **Settings > Devices**. See the [account security guide](/guides/account-security). * **Public proof metadata API:** Fetch metadata for any consumer protection — title, description, content type, file info, hash, and timestamp — without authentication. Useful for rendering custom proof pages and generating Open Graph link previews. See the [proof metadata endpoint](/api-reference/consumer/proof-metadata). * **Pricing calculator:** Estimate your monthly costs based on expected mint and verify volumes. The calculator pulls live regional rates for 27 countries so you see pricing in your local currency. * **Content protection and code authorship use-case pages:** Two new pages on the marketing site walk through real-world workflows — one for photographers, artists, writers, and researchers protecting creative work, and one for developers protecting source code with CI/CD integration. ### Updates * **Billing dunning and grace periods:** If a payment fails, the platform now follows a graduated access workflow — degraded, restricted, then suspended — with configurable grace periods so you have time to resolve the issue before losing access. See [billing](/billing/overview). * **Public rate-card API:** A new unauthenticated endpoint returns current plans, per-operation rates, and regional pricing multipliers so you can build cost estimates programmatically. See [billing](/billing/overview). * **Consumer session management:** You can now list active sessions and revoke all other sessions from the verify portal, in addition to the existing console-level session controls. See the [account security guide](/guides/account-security). **Week of April 14, 2026** Data retention, custom roles, consumer tiers, code authorship protection ## Data retention, custom roles, consumer tiers, and code authorship protection Configure data retention and legal holds for compliance, manage fine-grained access with custom roles, choose a consumer subscription tier, and protect source code with cryptographic attestations. ### New features * **Data retention policies:** Configure retention periods per data class — audit logs, consumer inbox, verification events, and webhook deliveries — with soft-only or soft-then-hard delete modes. Meets GDPR and data sovereignty requirements. See the [privacy center guide](/guides/privacy-center). * **Legal holds:** Place legal holds on specific data scopes to prevent deletion during investigations or disputes, regardless of your retention policy. * **Custom RBAC roles:** Create custom roles with granular permissions spanning attestations, issuers, users, audit, webhooks, API keys, governance, and settings. See [role-based access control](/security/rbac). * **Consumer subscription tiers:** Three pricing plans on the verify portal — Free (50 protections/month), Creator ($9/month, 500 protections), and Pro ($29/month, plan-dependent). Payment routes to the best provider for your region. * **Saved items:** Consumers can bookmark inbox items with optional notes and tags for quick reference. * **Verification history:** Browse previously read and archived verifications with filtering by state. * **Code authorship protection:** Protect source code, APIs, and documentation with cryptographic attestations. Covers single-file and full-repository protection with CLI, Node.js, Go, and Python SDK examples, plus CI/CD integration patterns. See the [code authorship guide](/guides/code-authorship). * **Issuer application review:** Submit issuer applications with supporting evidence. Platform reviewers approve, reject, or request additional information — with risk ratings and trust tiers assigned during approval. See the [issuer application guide](/guides/issuer-applications). * **Tenant announcements:** Receive platform-wide messages with priority levels (normal, urgent, critical) in a dedicated inbox with search, filtering, and read tracking. * **Pending approval status page:** New tenants waiting for platform approval see a clear status page with next steps and automatic redirect once approved. * **SDK quick-start page:** Copy-paste install commands and example code for the [JavaScript](/sdk/js), [Go](/sdk/go), and [Python](/sdk/python) SDKs, directly from the console settings. ### Updates * **SCIM provisioning guide:** A dedicated guide covering user and group CRUD, filtering, deprovisioning, group-to-role mapping, and IdP setup for Okta, Azure AD, and OneLogin. See [SCIM provisioning](/security/scim). * **Row-level security documentation:** New documentation explaining Postgres RLS tenant data isolation, session variable injection, and the full list of covered tables. See [row-level security](/security/rls). * **Abuse hardening documentation:** New documentation covering rate limiting tiers, request size limits, Ed25519 enforcement, and compliance mapping across B2C, B2B, and B2G segments. See [abuse hardening](/security/abuse-hardening). * **Onboarding checklist:** The [onboarding guide](/guides/onboarding) now details a seven-step checklist with progress tracking and resume behavior. **Week of April 7, 2026** Policy simulator, export controls, and policy lifecycle ## Policy simulator, export controls, and policy lifecycle Test issuance policies before enforcing them, control proof-bundle exports with rules, and manage policies through draft, active, and disabled states. ### New features * **Policy simulator:** Test how your [issuance policies](/guides/issuance-policies) evaluate a given request before deploying to production. Select a policy, enter a sample input, and see the decision, matched rules, and evaluation time — from the console or the [evaluate endpoint](/guides/issuance-policies#simulating-a-policy). * **Export control policies:** A new `BUNDLE_EXPORT` [policy category](/guides/issuance-policies#policy-categories) lets you apply rules to proof-bundle export and data-portability requests, alongside the existing `MINT` and `VERIFY` categories. ### Updates * **Policy lifecycle statuses:** Policies now support `DRAFT`, `ACTIVE`, and `DISABLED` [statuses](/guides/issuance-policies#policy-statuses). Save a policy as a draft while you iterate on rules, then activate it when ready — or disable it temporarily without deleting. * **Issuance policies:** The existing [issuance policies](/guides/issuance-policies) feature now includes detailed API examples for creating, listing, simulating, and deleting policies. **March 2026** Consumer platform, B2B2C delivery, new billing, and 50% price cut ## Consumer platform, B2B2C delivery, and new billing This release ships consumer content protection, white-labeled credential delivery for B2B2C workflows, enterprise SSO and SCIM, a new pay-per-use billing system with a 50% price cut, and a long list of reliability improvements. ### New features * **Consumer content protection:** Protect files directly from the [verify portal](/guides/content-protection) — drag-and-drop uploads with SHA-256 hashing, EXIF extraction, and [AI metadata detection](/guides/ai-metadata). Manage everything from [My Protections](/guides/consumer-portal). * **B2B2C credential delivery:** Deliver verified credentials to end consumers through a [white-labeled inbox](/guides/b2b2c). Recipients see issuer-branded credentials and can view claims, archive items, or open the public proof page — no account required. * **SAML SSO and SCIM:** Native SAML 2.0 single sign-on and SCIM user/group provisioning with [connection testing and role mapping](/security/saml-sso). * **Attestation supersede:** [Replace an attestation](/api-reference/attestations/supersede) with a new version while preserving the full audit trail. Useful for credential renewals, corrections, and key rotations. Available in the [Go](/sdk/go) and [Python](/sdk/python) SDKs. * **Pay-per-use billing with 50% price cut:** The new [billing system](/billing/overview) uses rate cards and plan-based gating. Mint dropped to $0.25 (from $0.50) and verify to $0.10 (from $0.20). * **Multi-provider payments:** Checkout routes to the best provider for your region — Stripe for most countries, Paystack for Nigeria, Flutterwave for Ghana, Kenya, and South Africa. See [provider routing](/billing/provider-routing). * **Billing add-ons:** Self-service [add-ons](/billing/overview) for Extra Seats, Priority SLA, Private Audit Logs, Compliance Pack, White-Label Branding, and more. * **Verification pack templates:** 26 ready-to-use [verification pack](/guides/verification-packs) templates spanning Identity, Compliance, Financial, Healthcare, Education, and Supply Chain categories. * **Public portfolios and badges:** Share protected work via [portfolio pages](/guides/portfolio) with OG tags. Embed [verification badges](/guides/badges) or download SVG certificates. * **Python SDK and Protect CLI:** A new [Python SDK](/sdk/python) and the `@truthlock/protect` [CLI](/guides/protect-cli) for content protection, including a GitHub Action for CI/CD. * **DID and JWKS discovery:** Public endpoints for resolving issuer identities via W3C DIDs and retrieving signing keys via [JWKS](/specification/did-jwks) for offline signature verification. * **Consumer account controls:** [API keys](/guides/consumer-portal) with a 5-key limit and 90-day expiry, [TOTP-based MFA and session management](/guides/account-security), and a self-service [privacy center](/guides/privacy-center) for data exports and account deletion. * **Data residency:** Lock tenant data to a specific geography (EU, US) for GDPR and data sovereignty compliance. * **Enterprise admin dashboard:** Cross-tenant analytics, bulk tenant management, and detailed drill-downs across users, API keys, webhooks, activity, and billing. * **Compliance review workflow:** Submit compliance evidence from settings. Administrators review, request info, and approve or decline with email notifications at each step. * **Purchase order billing:** Enterprise tenants can submit purchase orders as an alternative to credit card payment. ### Updates * **Billing limits enforcement:** API requests over quota return HTTP 402 with upgrade guidance. Portal verifications remain free. See [rate limits](/ops/limits) and [error codes](/ops/errors). * **Proof bundle integrity:** Bundles now include a `bundle_hash_b64url` integrity hash and `document_hash` for tamper detection. See the [proof bundle spec](/specification/proof-bundle). * **Webhook improvements:** Payloads include SHA-256 hashes, inactive endpoints are auto-skipped, and failed deliveries retry with status tracking. Endpoint limits scale by plan (1 free, 3 Starter, 10 Business, 25 Enterprise). See the [webhooks guide](/guides/webhooks). * **Interactive API playground:** The [API reference](/api-reference/attestations/mint) now has an interactive playground with pre-filled examples and environment switching. * **Automatic issuer provisioning:** Your signing identity is created automatically the first time you protect content — no manual setup. * **Enterprise branding:** Upload custom logos and brand assets for verification pages, emails, and proof bundles. * **Audit event reliability:** [Audit logs](/security/audit) now reliably capture every action. * **Support access sessions:** Support uses time-limited, scoped sessions with a full access log in your audit trail. * **Login security:** Error messages no longer reveal whether an email address is registered. * **Terms of Service and Privacy Policy:** New [Terms of Service](/policy) and [Privacy Policy](/trust/privacy) covering data processing, SLAs, and GDPR/CCPA rights. ### Bug fixes * Fixed a 500 error when generating signing keys for new tenants. * The [verify portal](https://verify.truthlocks.com) now handles anonymous verification without requiring authentication. * Resolved connection errors and signature validation failures when downloading or verifying proof bundles. * Fixed an infinite loop in the [protect flow](/guides/content-protection) for consumers with stale issuer records. * Console signups now correctly grant access, and the dashboard loads reliably after sign-in. * Fixed broken email templates for team invites, password resets, onboarding, and issuer notifications. * Resolved a 401 error preventing consumers from accessing their inbox. * Proof pages now display the correct attestation date. * [Audit log exports](/security/audit) complete successfully with correct IP address parsing. * The verification packs API endpoint is now correctly routed. * The public [transparency log](https://transparency.truthlocks.com) displays checkpoint history correctly. * Fixed console theme switching, attestation minting field issues, and dashboard stats accuracy. **February 2026** Public Verified Directory & Enhanced Search ## Search the Verification Network Citizens and businesses can now search a global public directory of Truthlocks-verified issuers. * **Verified Directory Database:** A dedicated portal providing issuer reputation scores. * **Enhanced API Error Codes:** We standardized our error verdicts for better predictability in programmatic consumption. Check out the new [Error Reference](/ops/errors). **January 2026** Sovereign Truthlocks Core & ZKP Private Verifications ## Launching Core Cryptography Upgrades This release overhauls the internal transparency engine to significantly reduce payload sizes while drastically improving verification speeds. * **Ed25519 Native Signatures:** Adopted Ed25519 as the primary algorithm for issuer and platform signatures, deprecating P-256 for minting. * **Proof Bundle Standardization:** Introduced a unified, single JSON cryptographic artifact for offline verifiability (`v1` spec). * **ZKP Preview:** Early access preview of zero-knowledge proofs designed for verifiable credentials without over-sharing personal information. **December 2025** Enterprise Packs & SDK Pre-Release ## Streamlined Go-To-Market Making it easier for enterprise engineering and compliance teams to evaluate the platform. * **Go, Python, and TS SDKs:** Released native SDKs across three languages mapping to Truthlocks `/v1/attestations` endpoints. * **Enterprise Asset Packs:** Documentation specifically tailored for B2G (Government), B2B, and Technical Integration architectures. # Core Concepts Source: https://docs.truthlocks.com/concepts Understanding tenants, issuers, attestations, and verification. This guide explains the fundamental building blocks of the Truthlocks platform. Understanding these concepts is essential for effective integration. ## Tenants A **tenant** is the top-level organizational unit in Truthlocks. Each tenant represents a distinct customer or organization with complete data isolation. | Property | Description | | - | - | | `id` | Unique UUID identifying the tenant | | `name` | Human-readable organization name | | `slug` | URL-safe identifier (e.g., `acme-corp`) | | `tier` | Subscription tier: FREE, STARTER, PROFESSIONAL, ENTERPRISE | | `status` | ACTIVE, SUSPENDED, or DELETED | ### Multi-tenancy controls * **Data Isolation:** Each tenant's data is completely isolated at the database level * **Resource Limits:** Rate limits and quotas are enforced per-tenant * **API Key Scoping:** API keys are bound to a single tenant and cannot access other tenants' data * **Audit Separation:** Audit logs are partitioned by tenant ## Issuers An **issuer** is an entity that can create and sign attestations. Issuers represent organizations, institutions, or services that make claims about subjects. > **Identity** > > Each issuer has a verified domain (e.g., `acme.edu`) that establishes their > real-world identity. > **Cryptographic Keys** > > Issuers register Ed25519 public keys used to verify attestation signatures. > **Trust Status** > > New issuers are activated immediately on creation. Higher trust tiers require an application review: ACTIVE → SUSPENDED. > **Trust Level** > > BASIC, VERIFIED, or PREMIUM based on identity verification depth. ### Issuer lifecycle ```text theme={null} ┌──────────────┐ │ CREATED │ └───────┬──────┘ │ auto-activated ▼ ┌──────────────┐ │ ACTIVE │ ← Ready to mint (BASIC trust) └───────┬──────┘ │ suspend │ │ apply for higher tier ▼ ▼ ┌──────────────┐ ┌──────────────┐ │ SUSPENDED │ │ IN REVIEW │ └──────────────┘ └───────┬──────┘ │ approve │ reject ▼ ▼ ┌──────────────┐ ┌──────────────┐ │ ACTIVE │ │ REJECTED │ │ (higher tier)│ │ (keeps BASIC)│ └──────────────┘ └──────────────┘ ``` > [!NOTE] > > New issuers are activated immediately with the **Basic** trust level. No manual approval is required to start minting attestations. To upgrade to a higher trust tier (Verified Organization, Government Entity, or Accredited Institution), submit an [issuer application](/guides/issuer-applications) for review. ## Attestations An **attestation** is a cryptographically signed claim made by an issuer about a subject. Attestations are the core primitive of the Truthlocks system. ### Attestation Structure ```json theme={null} { "id": "uuid", // Unique identifier "issuer_id": "uuid", // Who signed it "kid": "string", // Key used to sign "status": "VALID", // Current status "payload": { "subject": "string", // Who/what the claim is about "claim": "string", // Type of claim (e.g., "verified_email") "value": "any", // The actual claim data "metadata": {} // Optional additional data }, "signature": "base64", // Ed25519 signature "log_index": 42, // Position in transparency log "created_at": "datetime" } ``` ### Attestation Properties | Property | Description | | - | - | | **Immutable** | Once created, the payload and signature cannot be modified | | **Revocable** | Issuers can revoke attestations, updating status to REVOKED | | **Supersedable** | Issuers can [supersede](/api-reference/attestations/supersede) an attestation with a new version, creating an auditable chain while preserving the original | | **Portable** | Attestation ID can be shared and verified anywhere | | **Auditable** | Every operation is logged in the transparency log | ## Consumer protections A **consumer protection** is an attestation created through the simplified [consumer mint](/api-reference/consumer/mint) flow, designed for individual creators. You hash your file client-side (SHA-256) and submit the hash along with metadata like title, category, and content type. Truthlocks provisions your signing identity automatically on first use. The consumer mint response includes: | Field | Description | | - | - | | `protection_id` | Unique ID for the protection record | | `attestation_id` | The underlying attestation ID (used for verification) | | `content_hash` | The SHA-256 hash you submitted, echoed back for confirmation | | `protected_at` | Exact timestamp when the content was protected | | `verify_url` | Public proof page URL you can share with anyone | | `status` | Confirmation status (`protected`) | Each protection generates a public proof page. Anyone can fetch the proof page metadata via `GET /v1/public/proof/{attestation_id}` — no authentication required. This endpoint is designed for rendering proof pages and generating Open Graph link previews for shared URLs. See the [proof metadata endpoint](/api-reference/consumer/proof-metadata) for details. ## Risk signals A **risk signal** is a scored observation from a fraud-detection source — device fingerprinting, IP reputation, email verification, document analysis, or your own rules engine. You can ingest signals directly via the API, or submit raw identity events and let the platform normalize them into signals automatically. Each signal includes: | Field | Description | | :- | :- | | `signal_source` | Where the signal came from (e.g. `device_fingerprint`, `ip_reputation`, `login`) | | `signal_type` | What was detected (e.g. `velocity`, `geo_anomaly`, `ato`, `deepfake`) | | `risk_score` | Risk score from `0` (safe) to `100` (high risk) — scores at or above 80 trigger automatic review | | `subject_id` | Identifier of the entity being evaluated | | `subject_type` | The type of entity: `user`, `issuer`, `session`, `device`, `ip`, or `attestation` | | `payload` | Arbitrary metadata (IP addresses, geolocation, reasons) | ### Event normalization Instead of constructing risk signals manually, you can submit raw identity events — failed logins, invalid signatures, deepfake suspects — to `POST /v1/risk/events`. The platform maps each event to a canonical signal type and base risk score automatically. See the [normalize identity event API reference](/api-reference/risk/normalize-event). Risk signals are fully tenant-isolated using [row-level security](/security/rls) and form the foundation of the Anti-Fraud Identity Firewall. See the [risk signals guide](/guides/risk-signals) for integration details. ## Machine agents A **machine agent** is an AI agent, bot, or automated service registered with the [Machine Agent Identity Protocol (MAIP)](/guides/machine-identity). Each agent gets a unique identifier (`maip-agent:`) and an Ed25519 keypair for signing receipts. | Field | Description | | :- | :- | | `agent_id` | Unique MAIP identifier for the agent | | `name` | Human-readable agent name (e.g., `order-processor`) | | `type` | Agent type: `autonomous`, `supervised`, `delegated`, or `system` | | `scopes` | Permission scopes the agent is authorized to use | | `status` | Lifecycle status: `active`, `suspended`, or `revoked` | | `trust_score` | Continuous 0–100 behavioral trust score | Agents operate within **sessions** — short-lived, scope-bound execution contexts with automatic expiry. Every action an agent takes generates a cryptographically signed **receipt** that chains to the previous receipt for tamper-evident audit trails. Nine receipt types cover the full agent lifecycle: genesis, delegation, action, revocation, data attestation, model attestation, compliance, truth claim, and verification. See the [machine identity guide](/guides/machine-identity) for setup and the [agent authorization guide](/guides/agent-authorization) for the scope and session model. ## Proof bundles A **proof bundle** is a self-contained package that includes everything needed to verify an attestation offline, without contacting Truthlocks servers. ```json theme={null} { "attestation": { ... }, // Full attestation object "issuer": { "id": "uuid", "name": "Acme University", "domain": "acme.edu", "trust_level": "VERIFIED" }, "public_key": { "kid": "ed-key-2026", "algorithm": "Ed25519", "public_key_pem": "-----BEGIN PUBLIC KEY-----..." }, "transparency_proof": { "log_index": 42, "root_hash": "sha256:...", "inclusion_proof": ["hash1", "hash2", ...] } } ``` > [!NOTE] > > **Use Case:** Proof bundles are ideal for scenarios where verifiers may be > offline or want to independently verify without API calls. ## Verification Model Truthlocks verification checks multiple layers to determine if an attestation should be trusted: **1. Cryptographic Verification** Verify the Ed25519 signature matches the payload using the issuer's public key. **2. Status Check** Check if the attestation has been revoked or superseded by the issuer. Superseded attestations link to their replacement via `superseded_by_attestation_id`. **3. Issuer Trust Status** Confirm the issuer is in ACTIVE status and not suspended. **4. Key Validity** Verify the signing key was active at the time of attestation creation. ## Next Steps > **[Environments](/environments)** > > Learn about development vs production environments and configuration. > **[Authentication](/security/auth)** > > Deep dive into API keys, JWT tokens, and OAuth integration. # Platform architecture Source: https://docs.truthlocks.com/enterprise/architecture Technical boundaries between the Console, consumer portal, APIs and supporting services. Revision: 2026-10-13. ## Applications and responsibilities The business Console manages workspace records, keys, policies, workflows and billing. Platform Administration handles staff review and platform operations. The consumer Verify application provides individual account workflows and record checking. The public documentation site is maintained through Mintlify; it does not run the old Next.js documentation application. ```mermaid theme={null} flowchart LR C[Business Console] --> A[Authenticated service APIs] V[Consumer Verify] --> A P[Platform Administration] --> A A --> R[Identity and issuer registry] A --> S[Signing and verification] A --> T[Transparency and audit] A --> W[Workflows and automation] A --> B[Billing] R --> D[Managed PostgreSQL] S --> K[Managed signing keys] ``` ## Identity and isolation Services validate credentials and derive account context from authenticated identity. A caller-supplied tenant header is not authority to access another account. Database row-level policies provide another boundary, while individual operations enforce permissions and record ownership. Sandbox and production are separate operating environments. Record identifiers, API credentials and environment selection must agree. Do not treat a sandbox test as evidence of production acceptance. New accounts must complete the applicable onboarding and production-access review before production use. ## Evidence and verification The signing service produces signatures with a selected available key. The transparency service records log entries and proof references. Verification checks the evidence supplied and the available registry state. A record's signature establishes integrity and attribution to a key; it does not establish that every claim is true. Keep original payload bytes and proof bundles needed for independent checks. The printable certificate is a readable summary, not a replacement for cryptographic verification. ## Infrastructure and operating limits The current deployment uses Google Cloud for compute, managed PostgreSQL, secret storage and managed key operations. Email delivery uses Zoho SMTP. Available billing providers depend on the verified billing country and configured payment capabilities. Recovery objectives and availability commitments require a demonstrated restore and operational evidence. Do not infer a contractual SLA, multi-region recovery capability or completed certification from this architecture. Historical evidence depending on unavailable former signing keys cannot be made verifiable by relabelling it. # Information handling and document vault Source: https://docs.truthlocks.com/enterprise/information-handling Access, version integrity, retention and disposal for workspace documents. Revision: 2026-10-15. ## Private workspace vault Vault documents belong to one workspace and environment. An active workspace member can inspect and download accessible documents. Workspace owners and administrators manage uploads, versions and retention controls. A public documentation link never grants access to a workspace file. The initial vault API requires a signed-in workspace session; API-key access is not enabled. Each upload stores the file, SHA-256 checksum, authenticated uploader and version metadata together with its activity record. Downloads check stored size and checksum before returning an attachment. Uploaded files are not rendered as executable pages. Self-hosted document screening runs before storage and download. Detected threats, encrypted files, exceeded scan limits, an unavailable scanner or signatures older than 72 hours block the operation. Existing versions are screened on download. Scanning reduces risk; it does not guarantee that all threats are detected or review document accuracy. Identity evidence also requires screening before upload confirmation and staff download. Unconfirmed uploaded evidence remains unavailable for confirmation until checks pass. Supported files are PDF and UTF-8 text, Markdown, JSON or YAML. The limits are 5 MiB per file, 100 versions per document and 100 MiB of retained file contents per workspace environment. Private contents use the managed database's storage and backup controls; the vault is not a client-held-key or zero-knowledge storage service. ## Versions and access history A new upload creates a separate version. Prior version bytes and checksums are not edited in place. The document view shows version history and the latest 100 activity entries, including uploads, downloads and lifecycle decisions. History records the authenticated actor. This history is not a claim that an external auditor has reviewed the document. ## Retention and disposal Archive a document to stop new version uploads. A hold blocks purging. A minimum retention date can be extended but cannot be shortened or removed once set. Changes require an explicit reason and confirmation. An owner or administrator can purge file contents only after archive, with no active hold or future retention date. Purging removes the current stored bytes from all versions and preserves metadata, checksums and audit history. Backup copies expire under the backup retention policy. Files already downloaded by recipients cannot be recalled. Choose retention according to your organization's approved requirements. The product does not infer a legally required period from a document category. Cross-service erasure, legal review and organization-wide retention evidence require separate assessment. # Security governance and assurance Source: https://docs.truthlocks.com/enterprise/security-governance Current technical evidence, policy status, shared responsibilities and enterprise review materials. Revision: 15 October 2026. Truthlocks maintains technical specifications, security policies, a risk register and an evidence inventory. The policy set was rewritten for the Google Cloud platform on this date. Management approval and operating evidence are tracked separately; a document's existence does not establish that its procedures have been performed. Nnaa Igwiloh, CEO, explicitly approved the 13 reviewed document revisions, effective 15 October 2026. The [versioned decision record](https://github.com/truthlocks/truthlock/blob/main/docs/compliance/isms/decisions/POLICY-APPROVAL-2026-10-15.json) identifies their exact SHA-256 hashes and the source of the approval. The original reviewed text is preserved, including its earlier draft-status wording; the separate decision record establishes approval of those revisions. It does not establish completed operating activities or acceptance of every residual risk. ## Materials for your review | Material | Purpose | | - | - | | [Platform architecture](/enterprise/architecture) | Services, information flows and responsibility boundaries | | [Signing specification](/enterprise/signing-algorithms) | Supported algorithms, managed keys and known historical-key limits | | [Information handling](/enterprise/information-handling) | Private vault access, versions, retention and disposal | | [Enterprise setup](/enterprise/setup) | Organization identity, environments, SSO and acceptance checks | | [Versioned governance documents](https://github.com/truthlocks/truthlock/tree/main/docs/compliance/soc2) | Security, access, change, monitoring, incident, privacy and supplier procedures; see the exact revisions in the approval record | | [Governance working records](https://github.com/truthlocks/truthlock/tree/main/docs/compliance/isms) | Risk register, unfinished applicability review, evidence index, decision records and operating templates | Read each document's revision and its corresponding decision record. This library publishes the non-confidential policy-approval record. Staff records, contracts, identity evidence, detailed access reviews and confidential assurance reports belong in a restricted evidence store and are not published here. ## What technical evidence establishes A test report describes its exact scenario, version and result. An isolated database test can establish a transaction's behavior under that fixture. A hosted sandbox check establishes the exercised sandbox path. Neither proves that every production workflow, vendor integration or governance activity has passed. Mocked staff pages are labelled as UI checks rather than real privileged operations. Published evidence includes tenant-scoped usage records, duplicate-mint protection, sandbox charging exclusions, signed-record verification and reviewed invoice workflows. Automatic provider collection and merchant lifecycle acceptance remain separate from recording an invoice payment already received. ## Assurance status and requests This page does not claim SOC 2 examination completion or ISO/IEC 27001 certification. Readiness requires approved responsibilities and procedures, risk and applicability decisions, actual access and supplier reviews, training, recovery exercises, incident readiness, internal audit and corrective action evidence. Independent assessors determine whether the relevant examination or certification requirements are met. Contact [security@truthlocks.com](mailto:security@truthlocks.com) for a current assurance review. Agree the information scope, authorized recipients and confidentiality arrangements before sharing private evidence. Contractual region, retention, recovery and service-level commitments require approved terms; do not infer them from a technical example. The programme uses the [AICPA SOC resources](https://www.aicpa-cima.com/resources/landing/system-and-organization-controls-soc-suite-of-services) and [ISO/IEC 27001](https://www.iso.org/standard/27001) as references. Its operational mappings do not replace the complete applicable criteria or licensed standard. # Enterprise setup and acceptance Source: https://docs.truthlocks.com/enterprise/setup Prepare an organization, validate its workflows and retain the evidence needed for launch. Revision: 2026-10-15. ## Establish the workspace Register the organization's account and country. Identify the workspace owner and intended administrators. Use sandbox for initial integration and retain separate credentials for production. Do not share a staff account with business users. Submit the required identity or organization evidence through onboarding. Platform staff review the evidence and decide the applicable issuer trust classification. Registration, document upload, country verification and production approval are separate actions; one does not imply that all others have passed. ## Configure access Connect SSO for the organization's own identity provider using the Console configuration. Validate sign-in, membership assignment, sign-out and revoked access before rollout. Configure authenticator-based MFA where available and keep recovery procedures under the organization's access policy. Workforce-wide enforcement and periodic access-review evidence must be assessed explicitly. ## Prepare billing Staff must verify the registered billing country from submitted evidence before new paid billing is enabled. Country changes require review. Available providers and regional pricing follow the account's verified country. Do not assume that a provider shown in a directory supports every local payment method or that an existing subscription is automatically migrated. Negotiated usage rates are denominated in the currency explicitly recorded on the approved rate card. They are not automatically converted from USD. Invoice precision must match that currency: zero-decimal currencies require whole-unit amounts. Currencies requiring more than two decimal places remain unsupported. Unsupported or invalid rates hold usage for review instead of silently producing an invoice. Provider collection and payment-method availability must be validated separately. ## Accept the intended workflows Test issuance, verification with original payloads, expiry, revocation, webhook handling, failures and retries in the selected environment. Confirm API permissions, workspace boundaries and integration credentials. For automation, inspect actual completed or failed workflow outcomes rather than treating an accepted request as successful execution. Store current technical specifications and security documents in the workspace vault. Keep acceptance results, owners, dates and corrective actions. Use this library to understand behavior, then verify the deployed behavior relevant to your implementation. ## Security review materials Prepare an approved system scope, risk treatment, access review, incident response procedure, recovery test, vendor review and data-retention requirements. Technical templates do not establish completed controls or operating history. Any SOC 2 or ISO 27001 representation should be supported by the applicable controls and genuine evidence. # Signed record specification Source: https://docs.truthlocks.com/enterprise/signed-records How to construct, retain and verify an attestation without confusing claims with verification results. Revision: 2026-10-13. ## The signed payload Minting accepts either structured `schema` and `claims`, or `payload_b64url` containing the exact bytes to sign. Do not supply both forms. Preserve the payload, response and idempotency key. An encoded payload is not encryption. The record includes its identifier, issuer, issuance time, payload digest, declared signing algorithm, key identifier, signature and transparency references. Choose a key that is active, available for signing and supports the requested algorithm. Public-key registration alone does not make a private signing key available. ## Expiry For structured input, optional `expires_at_unix` is an integer Unix timestamp in seconds. It becomes part of the signed JSON payload. For encoded input, put this field at the root of the JSON payload before encoding it; do not send a separate unsigned expiry field. The date must be after issuance. Verification returns `EXPIRED` after that instant. Stored expiry cannot be extended or removed in place; issue a replacement. Omitting expiry does not invent a default lifetime. Historical records without a stored expiry are not assigned one retrospectively. Dates inside claims, such as `claims.expiry_date`, do not automatically set the attestation expiry. ## Issuer risk and claims The governance snapshot records the issuer's classification at issuance. An issuer risk rating is not an automated risk score for the document's contents. `unknown` means no assessment was recorded. New staff approvals require an evidence-supported assessment; they do not rewrite old snapshots. ## Transparency references `log.leaf_index` is zero-based: zero can be the first real entry. A missing or unavailable reference is distinct from zero. `log.leaf_hash` identifies the recorded leaf. These fields alone do not establish successful inclusion verification; check the proof and checkpoint against a trusted key. ## Verification and export Supply the original payload to check payload integrity and its signature. Read the verdict and reasons together: `INCOMPLETE` with `signature_verified: false` and `payload_not_provided` means payload-signature verification was not performed. A file hash comparison checks the supplied fingerprint against the stored fingerprint; it does not prove ownership or the truth of the file's contents. Private Console certificates require workspace access. A certificate download does not publish a record. Public verification is subject to the record and environment available to the public verifier. Use [Mint Attestation](/api-reference/attestations/mint), [verification](/api-reference/verify) and the [quickstart](/quickstart) for request formats. Retain an unchanged request when retrying a mint; changing signed fields under the same idempotency key is a conflict. # Signing algorithms and key custody Source: https://docs.truthlocks.com/enterprise/signing-algorithms Managed key generation, verification support, signature encoding and rotation limits. Revision: 2026-10-13. ## Choose a supported operation Algorithm names identify a cryptographic operation. They do not mean every key provider can generate every kind of key. | Algorithm | Managed generation on Truthlocks | Verification implementation | | - | - | - | | Ed25519 (`EdDSA` alias) | Yes | Ed25519 | | ES256 | Yes | P-256 and SHA-256 | | ES384 | Yes | P-384 and SHA-384 | | ES512 | No | P-521 and SHA-512 | | RS256 | Yes | RSA PKCS#1 v1.5 and SHA-256 | | RS384 | No | RSA PKCS#1 v1.5 and SHA-384 | | RS512 | Yes | RSA PKCS#1 v1.5 and SHA-512 | | PS256 | Yes | RSA-PSS and SHA-256 | | PS384 | No | RSA-PSS and SHA-384 | | PS512 | Yes | RSA-PSS and SHA-512 | Managed generation uses the supported [Google Cloud KMS algorithms](https://docs.cloud.google.com/kms/docs/algorithms). Requests for unsupported managed algorithms are rejected; the service must not relabel another algorithm to satisfy the request. Verification support does not provide a private signing key or enable a new issuance provider. ## Keys and encoding Use `provider: "KMS"` to generate a dedicated managed issuer key. New issuer keys do not reuse the shared historical platform key. Existing records keep their original key identifiers; replacing a key does not rewrite their signatures. Public-key registration takes base64url-encoded **DER SubjectPublicKeyInfo**. Registering a public key alone does not allow Truthlocks to mint with its private key. The mint endpoint does not ingest externally generated signatures. Payloads and signatures use base64url without padding. ECDSA signatures in Truthlocks records use **ASN.1 DER**, not the fixed-width concatenation used in JWS. RSA-PSS uses a salt length equal to the digest length. New software RSA signing requires at least 3072 bits; verification retains support for registered RSA public keys of at least 2048 bits. The ECDSA curve must match the algorithm. See the algorithm definitions in [RFC 7518](https://www.rfc-editor.org/rfc/rfc7518.html). ## Verify current state Online verification resolves the registered record's status, issuer and key. Supplying an inline envelope cannot override revocation or substitute another issuer. Original signed bytes are still required for a successful signature check. Offline verification cannot establish the latest online revocation status by itself. Use the [signed record specification](/enterprise/signed-records) for expiry and evidence semantics. Lost historical private keys cannot be recreated, and missing historical public keys cannot be guessed. A cryptographic algorithm test does not by itself establish HSM certification, compliance certification or a completed key-rotation exercise. # Technical library Source: https://docs.truthlocks.com/enterprise/technical-library Architecture, signed-record behavior, information handling and enterprise setup. This library describes the implemented system and its operating limits. It is separate from private files uploaded to a workspace vault. These documents are technical references; they are not an audit report, certification, contractual SLA or evidence of a completed security review. | Document | What it explains | | - | - | | [Platform architecture](/enterprise/architecture) | Applications, services, identity and data boundaries | | [Signed record specification](/enterprise/signed-records) | Payloads, signatures, expiry, issuer risk and proof bundles | | [Signing algorithms and key custody](/enterprise/signing-algorithms) | Managed generation, verification support, encoding and historical-key limits | | [Information handling](/enterprise/information-handling) | Workspace vault access, versions, retention and disposal | | [Enterprise setup](/enterprise/setup) | Identity, environments, SSO, billing and acceptance checks | | [Security governance and assurance](/enterprise/security-governance) | Current policy status, evidence requirements and security review materials | Each page carries a revision date. Changes are versioned in the [Truthlocks source repository](https://github.com/truthlocks/truthlock/tree/main/docs-mintlify/enterprise). Keep the revision used for your own review; a later page update is not a change to an existing signed record. For service availability, consult [System status](https://status.truthlocks.com). For integrations and installation links, use the [integration directory](https://truthlocks.com/resources/integrations). ## Console workflow execution Revision: 14 October 2026. The Console workflow library at [console.truthlocks.com/workflows](https://console.truthlocks.com/workflows) uses the shared Temporal execution service. The machine-identity orchestration pages in Console use this same editor. Domain automation services and the public `/v1/orchestrate/workflows` API have separate contracts; do not interchange their definitions. Start with a **Start** step, connect the actions you need, and end the path with **Finish**. Saving a definition records configuration. A completed run, with its recorded step outcomes, is the evidence that execution succeeded. | Step | Required configuration | Recorded behavior | | - | - | - | | Generate with Gemini | Task instructions; maximum response tokens from 1 to 32768 | Includes run input and earlier results as context; saves response text, model, token count and estimated cost. Requiring structured output rejects responses that are not JSON objects. | | Request human approval | Existing workspace reviewer user IDs, review instructions and a deadline of 1–168 hours | Persists the review request and decision. Approval continues the path; rejection or expiry fails it. | | Send an email | Exactly one recipient, a subject of 1–200 characters, and a plain-text message | Records SMTP provider acceptance. This does not prove inbox delivery. The engine does not automatically retry an uncertain delivery. Named templates and variable substitution are not supported. | Keep credentials out of prompts, run input and step configuration. AI steps send their context to the configured Gemini service. A workflow response is generated content, not an independently verified attestation. ### Data mappings The `transform` step accepts a `mappings` object in its saved configuration. Values can be JSON literals, nested objects and arrays, or an object containing only `$ref`. References read the current run's `trigger_data` or an earlier step's output in `prior_outputs`. ```json theme={null} { "mappings": { "invoiceAmount": { "$ref": "/trigger_data/invoice/amount" }, "reviewDecision": { "$ref": "/prior_outputs/review/decision" }, "source": "workflow" } } ``` For this example, the run input must contain `invoice.amount`, and the earlier step with ID `review` must output `decision`. Array references use zero-based indexes, such as `/trigger_data/items/0/amount`. Within a field name, encode `/` as `~1` and `~` as `~0`. Missing fields, invalid indexes and unsupported `expression` configurations fail the step. An existing field whose value is `null` remains `null`. Mappings do not execute JavaScript, SQL or arbitrary expressions. A step allows 1–100 output mappings, with bounded nesting and traversal. ### Current boundaries External tool connectors are not operational through the shared engine yet. The step picker does not offer those connectors as executable actions. A saved legacy definition can still contain an unsupported step; saving it is not proof that it can run. Review its recorded execution result before relying on it. Workflow runs do not automatically produce a signed proof bundle. Use the attestation flow separately when a signed record is required. Environment isolation and continued-run recovery are still part of the remaining enterprise acceptance work. # Environments Source: https://docs.truthlocks.com/environments Match your API host, credential, and workspace environment. ## Base URLs | Environment | API base URL | Key prefix | | - | - | - | | Sandbox | `https://sandbox-api.truthlocks.com` | `tl_test_` | | Production | `https://api.truthlocks.com` | `tl_live_` | Create credentials for the intended environment in [Console](https://console.truthlocks.com). Production access depends on workspace approval and permissions. A sandbox key does not become a production key by changing the URL. ## Try it in the API playground Select the server offered by the endpoint, then supply the credential type shown for that operation. Public health endpoints require no API key. Some user-management operations require a bearer token with the appropriate role, rather than a service API key. Requests sent from the playground are real requests. Write operations can create records, consume quota, or trigger notifications even when used for testing. Use your sandbox workspace and avoid real recipient addresses in test requests. ## Workspace and session selection The service derives the workspace and environment from authenticated credentials. Do not add `X-Tenant-ID` or an environment header to override them. The Console environment switcher updates the signed-in session. It does not change existing API keys used by a separate backend application. Use a key issued for the target environment in that application. Environment administration and session activation are distinct operations. Activating a session requires user authentication; sending an API key to a session-activation endpoint does not switch subsequent API-key requests. ## Limits and retention Check the workspace's current billing and environment settings for quotas, retention, and available features. This page does not promise a fixed sandbox allowance, weekly log resets, permanent production retention, or a contractual uptime guarantee. Before going live, verify the target host, key environment, issuer, signing key, permissions, and successful read/write behavior using your own approved workspace. # Account security Source: https://docs.truthlocks.com/guides/account-security Set up multi-factor authentication, manage passwords, and control active sessions. Truthlocks gives you tools to lock down your account: multi-factor authentication (MFA), password management, and session controls. Access these settings from your dashboard at `verify.truthlocks.com/security`. ## Multi-factor authentication MFA adds a second verification step when you sign in. Truthlocks supports time-based one-time passwords (TOTP) through any authenticator app such as Google Authenticator, Authy, or 1Password. ### Enable MFA **1. Open security settings** Open **Security**, then **Manage your authenticator** and **Set up Google Authenticator**. Confirm your current Truthlocks password. **2. Scan the QR code** Open your authenticator app and scan the QR code displayed on screen. If you cannot scan the code, copy the setup key manually. **3. Enter verification code** Type the 6-digit code from your authenticator app and submit the setup form. Check the confirmed result, then save the single-use recovery codes privately. > [!WARNING] > > Keep recovery codes separate from your phone. Each code can replace an app code once. Do not share your setup key, QR code or recovery codes. Enabling or disabling MFA, or replacing recovery codes, revokes your existing browser sessions. Save new recovery codes privately before signing in again. ### Disable MFA To turn off MFA, open the authenticator settings and **Disable authenticator**. Confirm your current password and a fresh authenticator code or unused recovery code. Wait for a confirmed result. ### Platform Admin access Truthlocks Platform Admin requires an MFA-verified sign-in. Staff who have not enrolled can access their own authenticator setup, but cannot use privileged platform operations. After setup, save recovery codes privately and sign in again with an authenticator or recovery code. Disabling an authenticator does not remove this access requirement; the account must enroll again before privileged access is restored. This staff policy does not enable organization-wide MFA enforcement for business tenants. Business and consumer users can manage their own authenticator from account security settings. ## Password management Change your password from the Security page. New passwords must contain 10–72 UTF-8 bytes and differ from the current password. For ordinary English characters, this is 10–72 characters; other characters can use more than one byte. **1. Enter your current password** Type your existing password to verify your identity. **2. Set a new password** Enter and confirm a new password (minimum 10 characters). **3. Save** Click **Change password**. After a confirmed change, this session remains signed in and other existing browser sessions are revoked. > [!TIP] > > Use a password manager to generate a strong, unique password for your > Truthlocks account. ### Forgot your password If you cannot remember your password, reset it from the sign-in page: **1. Click Forgot Password** On the sign-in page, click the **Forgot Password** link below the password field. **2. Enter your email** Type the email address associated with your account and click **Send Reset Link**. **3. Check your inbox** Open the password reset email and click the reset link. The link expires after a limited time. **4. Set a new password** Enter and confirm a new password (minimum 10 characters), then click **Reset Password**. A confirmed reset revokes prior browser sessions; sign in again with the new password. > [!NOTE] > > For security, the confirmation message is always shown regardless of whether > the email address is registered. This prevents account enumeration. ## Session management ### Consumer portal sessions Open [Security > Browser sessions](https://verify.truthlocks.com/security/sessions). The list shows up to 100 unexpired sessions observed by Truthlocks in your current account. Sessions that existed before tracking was enabled appear when they next contact an API. * **Review sessions:** Check for any sessions you do not recognize. * **Sign out other sessions:** Open the full review page, read the scope, select the confirmation checkbox and submit. Wait for the confirmed result. Other older tokens are revoked even when they have not appeared in the list. > [!NOTE] > > Signing out other sessions does not change your password. If you believe your > account is compromised, change your password and enable MFA. API keys, connected applications and external identity-provider sessions are separate credentials and require separate review. ### Console sessions Business users can review their own sessions at [Settings > Sessions](https://console.truthlocks.com/settings/sessions). The list is scoped to the signed-in user and workspace; it is not a list of everyone in the organization. | Field | Description | | :- | :- | | **Browser information** | User-agent label supplied by the browser; not verified device identity | | **Last API activity** | Recorded activity, updated at most once per minute | | **Expires** | When the token expires | | **Current session** | “This session” identifies the token used for the request | Use **Sign out other sessions** and its review page to preserve this session while revoking other existing user tokens. Individual rows do not open a revocation popup. Normal **Sign out** revokes the current token before clearing the browser cookie; an unavailable backend produces an error instead of a false success. Revoked tokens are rejected on their next authenticated API request. Requests already in progress may finish, and a page can remain visible until it makes another request. Session revocation does not erase cached information or invalidate API keys. ## Recommended security checklist > **Enable MFA** > > Add a second check to new password sign-ins. Keep authenticator and recovery codes private. > **Use a strong password** > > Choose a password that is at least 10 characters and unique to Truthlocks. > Avoid reusing passwords from other services. > **Review sessions regularly** > > Check your active sessions periodically and revoke any you do not > recognize. > **Keep your email secure** > > Your email is used for password resets. Make sure it also has MFA enabled. ## Next steps > **[Privacy center](/guides/privacy-center)** > > Export your data or request account deletion. > **[Content protection](/guides/content-protection)** > > Learn how to protect your content with cryptographic attestations. # Independent agent reviews Source: https://docs.truthlocks.com/guides/agent-approvals Request human review, collect distinct decisions, and enforce the final outcome in your application. Agent approvals record human decisions about a proposed agent action in one workspace environment. They are separate from workflow-engine approvals, permission grants, cryptographic action receipts, and Temporal execution. ## Before you start * Use an active agent from the same workspace and environment as your credential. * Create requests using a workspace API key or a signed-in workspace user. * Reviewers must be active human workspace members with the workspace-level `tenant:governance:approve` permission. An organization-only role is insufficient. * The requester cannot approve or reject their own request. Each reviewer may decide once. API keys cannot cast human votes. In Console, open **AI Agents → Agent Approvals**. The request, review, and cancellation forms each have a dedicated page. Save the request link to return to it after it leaves the pending queue. ## Create a request This example requests two independent approvals in a one-hour window. Replace the agent identifier with an existing sandbox agent; a production agent cannot be used with a sandbox credential. ```bash theme={null} curl --fail-with-body https://sandbox-api.truthlocks.com/v1/approvals \ -H "X-API-Key: $TRUTHLOCKS_API_KEY" \ -H 'Content-Type: application/json' \ --data '{ "agent_id": "YOUR_SANDBOX_AGENT_ID", "action": "publish reviewed report", "resource": "reports/quarterly-review", "scope": "reports:publish", "risk_level": "high", "justification": "The report has completed technical review. Confirm the approved version before publication.", "required_approvals": 2, "ttl_minutes": 60 }' ``` The `201` response contains `id`, `requested_by`, `status: "pending"`, `current_approvals: 0`, and `expires_at`. Save `id`; creation does not publish the report or create a background workflow. ## Review with a human session Use Console for interactive decisions. If your integration uses the API, supply the reviewer's short-lived workspace bearer session. Do not substitute an API key or embed a session token in source code. ```bash theme={null} curl --fail-with-body "https://sandbox-api.truthlocks.com/v1/approvals/$APPROVAL_ID/approve" \ -H "Authorization: Bearer $TRUTHLOCKS_REVIEWER_TOKEN" \ -H 'Content-Type: application/json' \ --data '{"reason":"Reviewed the exact report version and its supporting evidence."}' ``` The first approval in this example returns `status: "pending"` and `current_approvals: 1`. A different authorized reviewer must supply the second vote. Reusing the same reviewer returns a conflict. One rejection immediately changes the request to `rejected` regardless of earlier approvals. The service verifies current membership permissions, request ownership, expiry, and existing votes inside the decision transaction. Votes and the audit event commit together. Decisions cannot be edited or deleted through these APIs. ## Check and enforce the outcome ```bash theme={null} curl --fail-with-body "https://sandbox-api.truthlocks.com/v1/approvals/$APPROVAL_ID" \ -H "X-API-Key: $TRUTHLOCKS_API_KEY" ``` The detail response includes the reviewer history. Only proceed when `status` is `approved` and the request still matches the exact agent, action, resource, and scope your application intends to use. Your application must also enforce current access permissions, agent status, and its own single-use or replay controls. These approval records do not provide an automatic execution or consumption mechanism. | Status | Meaning | | - | - | | `pending` | More independent approvals are required. | | `approved` | The configured quorum was reached within the review window. | | `rejected` | An independent reviewer rejected the request. | | `expired` | A pending request passed its review deadline. | | `cancelled` | Its original requester cancelled it. | The review deadline limits when decisions can be submitted. It does not turn an already approved request into an expiring access token. Define any execution deadline in your own application. ## Queue, cancellation, and errors `GET /v1/approvals` returns an array of at most 100 oldest pending, unexpired requests. It has no pagination or historical-status filter. The queue omits individual decision history; fetch a request by ID for that history. The original requester can send `POST /v1/approvals/{approvalID}/cancel` with a nonblank `reason`. A request cannot be reopened after cancellation, rejection, approval, or expiry. Create a new request if the proposed action changes. | HTTP status | What to check | | - | - | | `400` | Field limits, a UUID request ID, and a nonblank decision reason. | | `403` | Current workspace reviewer permission, requester self-review, API-key voting, or cancellation ownership. | | `404` | Request or active agent belongs to the selected workspace environment. | | `409` | Request is final, expired, or this person already voted. | These records support your review process; they do not establish SOC 2 compliance, ISO certification, identity-document verification, or the correctness of submitted evidence. # Agent Authorization Source: https://docs.truthlocks.com/guides/agent-authorization Scope-based authorization, session management, and tool invocation for AI agents. # Agent Authorization Every AI agent in the Truthlocks platform operates under a strict authorization model. Agents must be registered, assigned scopes, and create time-bounded sessions before they can take any action. ## Authorization Flow ``` Register Agent → Assign Scopes → Create Session → Execute Actions → Terminate Session │ │ │ │ │ ▼ ▼ ▼ ▼ ▼ agent_id scope_ids session_token audit_logged cleanup ``` > [!TIP] > > All agent authorization endpoints — scopes, sessions, and tools — have an interactive API playground. Open any endpoint in the [Agent Sessions & Tools](/api-reference/machine-identity/sessions/create) API reference and click **Send** to try it against the Sandbox. ## Scope model Scopes follow a hierarchical `resource:action` pattern. When an agent requests a session, it can only request scopes that were assigned at registration. ### Defining Custom Scopes ```bash theme={null} curl -X POST https://api.truthlocks.com/v1/scopes \ -H "X-API-Key: $API_KEY" \ -d '{ "name": "invoices:approve", "description": "Approve invoices up to configured threshold", "constraints": { "max_amount_cents": 500000, "require_dual_approval_above": 100000 } }' ``` ### Built-in Scopes | Scope | Description | | - | - | | `agents:read` | List and inspect agents | | `agents:write` | Register and update agents | | `receipts:write` | Mint action receipts | | `attestations:read` | Read attestation data | | `attestations:write` | Create new attestations | | `trust-scores:read` | Read trust score data | | `trust-scores:compute` | Trigger trust score recomputation | | `delegations:offer` | Offer cross-tenant delegation | | `delegations:accept` | Accept delegation offers | | `compliance:write` | Create compliance checks | | `orchestrations:execute` | Execute multi-agent workflows | | `datasets:attest` | Attest dataset provenance | | `models:attest` | Attest model lineage | ## Session Management Sessions provide time-bounded execution contexts with automatic expiry and optional IP allowlisting. ### Creating a Session ```bash theme={null} curl -X POST https://api.truthlocks.com/v1/agent-sessions \ -H "X-API-Key: $API_KEY" \ -d '{ "agent_id": "maip-agent:01JXXXX", "scopes": ["receipts:write", "attestations:read"], "ttl_seconds": 3600, "ip_allowlist": ["10.0.0.0/8"], "metadata": { "task": "process-quarterly-invoices", "initiated_by": "user:alice@corp.com" } }' ``` **Response:** ```json theme={null} { "id": "maip-session:01JYYYY", "agent_id": "maip-agent:01JXXXX", "token": "mst_live_...", "scopes": ["receipts:write", "attestations:read"], "expires_at": "2026-04-06T13:00:00Z", "status": "active" } ``` ### Session Lifecycle | Status | Description | | - | - | | `active` | Session is valid and accepting requests | | `expired` | TTL elapsed — automatic cleanup | | `terminated` | Explicitly ended by user or system | | `suspended` | Paused due to anomaly detection | ### Terminating a Session ```bash theme={null} curl -X DELETE https://api.truthlocks.com/v1/agent-sessions/maip-session:01JYYYY \ -H "X-API-Key: $API_KEY" \ -H "Content-Type: application/json" \ -d '{ "reason": "Task completed" }' ``` ## Tool Registration & Invocation Agents can register tools they expose and invoke tools registered by other agents (subject to scope checks). ### Register a Tool ```bash theme={null} curl -X POST https://api.truthlocks.com/v1/tools \ -H "X-API-Key: $API_KEY" \ -d '{ "agent_id": "maip-agent:01JXXXX", "name": "generate-invoice", "description": "Generate PDF invoice from order data", "input_schema": { "type": "object", "properties": { "order_id": { "type": "string" }, "format": { "type": "string", "enum": ["pdf", "html"] } }, "required": ["order_id"] } }' ``` ### Invoke a Tool ```bash theme={null} curl -X POST https://api.truthlocks.com/v1/tools/invoice-generator/invoke \ -H "X-API-Key: $API_KEY" \ -d '{ "session_id": "maip-session:01JYYYY", "input": { "order_id": "ord_123", "format": "pdf" } }' ``` Every tool invocation is: 1. **Scope-checked** — the session must have the required scope 2. **Rate-limited** — per your plan's tool invocation quota 3. **Audit-logged** — full input/output recorded in the audit trail 4. **Metered** — counted against your billing entitlements ## Security Best Practices > [!WARNING] > > Never embed session tokens in client-side code. Session tokens grant the full scope of the session and should be treated as secrets. 1. **Principle of least privilege** — Request only the scopes needed for the current task 2. **Short-lived sessions** — Use the shortest practical TTL (default: 1 hour) 3. **IP allowlisting** — Restrict sessions to known network ranges 4. **Rotate credentials** — Regenerate agent signing keys on a regular schedule 5. **Monitor trust scores** — Set alerts when trust scores drop below thresholds 6. **Use the kill switch** — Immediately revoke compromised agents ## Next steps > **[MAIP policies](/guides/maip-policies)** > > Runtime enforcement rules based on trust scores, scopes, and delegation depth. > **[Trust Scores](/guides/trust-scores)** > > Continuous behavioral trust evaluation for agents. > **[Cross-Tenant Delegation](/guides/cross-tenant-delegation)** > > Allow agents to act across organizational boundaries. # AI metadata extraction Source: https://docs.truthlocks.com/guides/ai-metadata How Truthlocks uses AI to automatically categorize and describe your protected content. When you protect content on Truthlocks, AI automatically analyzes your file to generate metadata — including a suggested title, description, category, and tags. This enriches your protection records and makes them easier to search, share, and verify. ## How it works When you upload a file on the Protect page, Truthlocks sends the file name, type, size, and a preview (for text-based files) or EXIF data (for images) to an AI model. The file itself stays in your browser — only metadata is sent for analysis. **1. File selected** You select or drag a file onto the Protect page. **2. Metadata extracted** Truthlocks reads basic file properties (name, MIME type, size) and, where applicable, extracts EXIF data from images or a text preview from code and document files. **3. AI analysis** The extracted metadata is sent to the AI model, which returns a structured response with category, content type, description, suggested title, tags, and more. **4. Review and edit** AI-generated fields appear as suggestions. You can edit any field before confirming your protection. > [!NOTE] > > AI metadata extraction is automatic and runs in the background as soon as you > select a file. You always have the final say — edit or override any > suggestion before protecting. ## Supported categories The AI classifies your content into one of the following categories based on file type and content analysis: | Category | File types | | - | - | | **Photography** | JPEG, PNG, WebP, TIFF, RAW formats | | **Digital art** | PSD, AI, SVG, Procreate, HEIC | | **Source code** | JS, TS, Python, Go, Rust, Java, C/C++, and 30+ other languages | | **Document** | PDF, DOCX, TXT, Markdown, LaTeX | | **Music** | MP3, WAV, FLAC, AAC, MIDI | | **Video** | MP4, MOV, AVI, WebM, MKV | | **Design** | Figma, Sketch, XD files | | **Data** | CSV, JSON, XML, SQL, Parquet | ## Generated metadata fields The AI produces the following fields for each file: | Field | Description | | - | - | | `category` | Content category (see table above) | | `content_type` | Specific content type within the category (e.g., "landscape photography") | | `suggested_title` | A human-readable title based on file name and content | | `description` | A short description of what the file contains | | `tags` | Relevant keywords for search and discovery | | `language` | Programming language (for source code files) | | `framework` | Detected framework or library (for source code files) | | `license_hint` | Detected or suggested license (if identifiable) | | `subject_matter` | The primary subject or topic of the content | ## Proof summaries Every protection certificate includes an AI-generated summary that describes what was protected and when. The summary appears on the public proof page below the certificate details and is designed for sharing and link previews. Proof summaries are generated automatically when anyone views a proof page. You do not need to configure or trigger them. | Detail | Description | | - | - | | **Content** | A 2–3 sentence explanation of the protection — what was protected, its category, and the protection date | | **Fallback** | If AI is unavailable, a template-based summary is generated instead so the proof page always displays a readable description | | **Indicator** | AI-generated summaries show a small sparkle icon and an "AI-generated summary" label | | **Caching** | Summaries are cached per proof page and revalidated every five minutes. Subsequent visitors see the cached version, reducing latency and AI usage | ### How caching works When the first visitor loads a proof page, the platform generates an AI summary and caches it. For the next five minutes, all visitors see the cached result. After five minutes, the next request triggers a fresh AI generation and refreshes the cache. If the AI model is unavailable at generation time, the cached result is a template-based fallback instead. The cache still applies — the fallback is served for up to five minutes before the platform retries AI generation. > [!NOTE] > > Proof summaries are cached and revalidate every five minutes. The first visitor to a proof page triggers the summary generation, and subsequent visitors see the cached version until it refreshes. You do not need to manage caching yourself. ### Fallback summaries When the AI model is unavailable, the proof page displays a deterministic template summary instead. Template summaries include: * The content category and protection date. * A note that the cryptographic proof is anchored to the Truthlocks transparency log. * A provenance indicator — if the content was uploaded by a person (rather than via API), the summary includes a note confirming human submission. Template summaries do not show the sparkle icon, so you can always tell whether a summary was AI-generated. > [!TIP] > > Proof summaries use only the metadata you provided when protecting your content — title, description, category, and date. Your original file is never accessed. ## Similarity detection Before minting a protection, Truthlocks checks whether a similar file hash already exists. This prevents duplicate protections and alerts you if the content was previously registered — either by you or by another user. If a match is found, you see a warning with details about the existing protection before proceeding. Each match includes: * **Similarity score** — how closely the content matches an existing protection. * **Owner** — the username of the person who protected the original. * **Date** — when the original protection was created. * **Exact match flag** — whether the content hash is identical to an existing record. ## Using AI metadata with the API When calling the mint endpoint, you can include AI-extracted fields to enrich your protection record: ```bash theme={null} curl -X POST https://api.truthlocks.com/v1/consumer/mint \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "content_hash": "e3b0c44298fc1c149afbf4c8...", "title": "Sunset at Big Sur", "description": "Landscape photograph taken at Pfeiffer Beach", "file_name": "sunset-big-sur.jpg", "file_size": 4521984, "content_type": "landscape photography", "category": "photography", "tags": ["landscape", "sunset", "california", "beach"], "visibility": "public" }' ``` > [!TIP] > > When using the API, you can skip AI extraction and provide your own metadata > directly. The AI extraction feature is available on the web interface and > runs automatically. ## Privacy AI metadata extraction follows the same privacy model as the rest of Truthlocks: * **Your file never leaves your browser.** Only the file name, MIME type, size, and a small preview or EXIF data are sent for analysis. * **No file content is stored** by the AI service. Metadata is generated in real time and returned to your browser. * **You control what ships.** Review and edit all AI-generated fields before confirming your protection. ## Next steps > **[Content protection](/guides/content-protection)** > > Full guide to protecting your content with cryptographic attestations. > **[Consumer portal](/guides/consumer-portal)** > > Manage protections, credentials, and settings from your dashboard. > **[Embeddable badges](/guides/badges)** > > Add verification badges to your website or README. > **[Public portfolio](/guides/portfolio)** > > Showcase verified work on a public profile page. # AI orchestration and workflow execution Source: https://docs.truthlocks.com/guides/ai-orchestration Understand workflow execution, MAIP tracking records, recorded outcomes, and current integration boundaries. Truthlocks has two distinct workflow interfaces. Choose the interface before building an integration; their identifiers, payloads, and execution behaviour differ. | Interface | What it does | Where to use it | | - | - | - | | Console workflow engine | Launches a saved graph through a Temporal worker and records its step and final outcomes. | Console workflow designer and run history. | | MAIP orchestration and workflow APIs | Store definitions, execution tracking records, and related agent evidence. These routes do not start the Console Temporal worker. | Public `/v1/orchestrate/...` references. | ## Console workflow runs Save the graph in the workflow designer, review its connections, and launch it with the intended trigger data. A successful launch response means Temporal accepted the request; it does not mean the work finished. Open **Run history** and refresh the record to inspect: * `pending`: the request is saved, but worker start has not yet been recorded. * `running`: the worker recorded its start. * `completed`: the selected steps completed and the final result was saved. * `failed`: a step or workflow operation failed. Inspect recorded steps before retrying side effects. * `cancelled`: cancellation was observed and the worker saved the final outcome. Choose **Settings → Environments** before creating or launching a workflow. Switching environments does not copy definitions or runs. A workflow from another environment cannot be read, published, paused or launched through the current environment. Production selection still requires workspace approval. This record boundary does not simulate external providers: a supported AI or email step may make a real provider request. Use synthetic inputs and explicitly authorized recipients during testing. New runs capture the saved graph at launch. Later edits do not change that execution. The result contains the definition version and SHA-256 digest, Temporal execution identifiers, timestamps, costs reported by steps, and JSON step output. Older runs may not have this information; it is not reconstructed or fabricated. The runner rejects cycles and invalid connections. Ready steps execute in definition order. A shared next step waits for its predecessors and executes once when at least one incoming path is selected. A branch chooses an exact condition before considering its default connection. A run result is operational evidence, not automatically a cryptographic proof bundle. `proof_status: "not_generated"` explicitly means no bundle was generated. A zero recorded cost does not establish that an external provider charged nothing. ### Email notification step Use one recipient per step and supply explicit text: ```json theme={null} { "id": "notify-reviewer", "name": "Notify reviewer", "type": "notify", "config": { "channel": "email", "recipients": ["reviewer@your-company.example"], "subject": "Your review is ready", "text_body": "Open your workspace to review the recorded result." } } ``` The result reports `provider_accepted` and a message identifier after the configured SMTP provider accepts the message. It does not guarantee inbox delivery. Named templates, multiple recipients in one step, and non-email channels are not supported by this activity. Automatic retries are disabled because SMTP cannot guarantee exactly-once delivery. Investigate an unconfirmed attempt before sending again. ### Execution boundaries to account for * A launch timeout can leave a `pending` record even if Temporal accepted the request. Check that run before launching another; automated dispatch reconciliation remains incomplete. * Console human-review steps persist assigned approval requests. Authorized approve/reject decisions and their Temporal outcomes have passed scoped live acceptance. A separate MAIP agent-approval record does not signal a Console workflow. * AI steps use the configured Gemini gateway; a synthetic Temporal-to-Gemini run has passed live acceptance. Validate your own prompt, output requirements and costs. * External `tool_call` steps are not available in the deployed connector runtime. Keep these graphs as drafts; they cannot be used for production tool automation. An external integration package does not enable a workflow connector. * A background worker reconciles known Temporal execution identifiers, including terminal failure and continued-as-new transitions. It does not infer successful effects from missing history, and cannot recover an unknown dispatch identity. * Workflow definitions, runs, steps and approvals created after environment isolation are scoped to the selected workspace environment. Historical records without verified environment attribution remain available to platform oversight; they are not silently assigned to production. Broader provider-side isolation and all external side-effect recovery are not established by this storage boundary. * Workflow audit events are saved with state changes. This does not establish completed export to every external audit destination or an independently certified retention policy. ## MAIP execution tracking The public [orchestration execution reference](/api-reference/machine-identity/orchestrations/execute) documents `pattern`, `orchestrator_id`, and `agent_ids`. Use its generated fields and dropdowns for the complete request contract. An HTTP `201` response creates a tracking record. Its initial `running` status is not proof that agents or tools ran. Execute and supervise those actions in your application until a supported executor is connected. The [MAIP workflow run reference](/api-reference/machine-identity/workflows/execute) is a separate record-creation route requiring `trigger_agent_id`. Do not substitute Console graph IDs or assume that a supplied schedule registers a Temporal schedule. New automatically generated MAIP receipts use the configured managed signer. Verify a receipt through the receipt verification API. Its signature authenticates the recorded statement; it does not prove that an unexecuted business action occurred. Some preserved historical records have unverifiable placeholder signatures. For independent human decisions about a proposed agent action, use [agent approvals](/guides/agent-approvals). Approval records do not automatically execute or resume a workflow. # Account takeover detection Source: https://docs.truthlocks.com/guides/ato-detection Detect account takeover attempts with velocity-based heuristics, automatic risk scoring, and real-time alerts. The account takeover (ATO) detection API monitors login activity per subject and flags suspicious patterns in real time. It tracks failed login velocity in a rolling one-hour window, assigns a risk level based on configurable thresholds, and automatically creates alerts and [risk signals](/guides/risk-signals) when those thresholds are crossed. > [!NOTE] > > ATO detection is part of the [Anti-Fraud Identity Firewall](/guides/risk-signals). Alerts and risk signals flow into the same pipeline as other fraud signals, so you can query and review them from the **Risk & Fraud > Signals** console page or the [list signals endpoint](/api-reference/risk-signals/list). ## How it works **1. Send login events** Call `POST /v1/risk/ato/evaluate` each time a login event occurs — failed attempts, repeated failures, new device logins, or successful logins. **2. Velocity tracking** The platform increments (or resets) the failed login counter for the subject in a rolling one-hour window. Successful logins reset the window. **3. Risk level assignment** A risk level is derived from the current failed login count. The response includes the risk level, numeric score, and current counter value. **4. Automatic alerts and signals** When a subject crosses a threshold, the platform creates an alert and ingests a risk signal with `signal_type: "ato"`. You don't need a separate API call. **5. Review and respond** Query ATO profiles, list alerts, and review signals in the console or via the API to investigate and respond to threats. ## Prerequisites * An active Truthlocks tenant with an API key * Login event data from your authentication system (failed logins, successes, new device events) ## Evaluating a login event Send a `POST` request to `/v1/risk/ato/evaluate` with the subject and event details: ```bash cURL theme={null} curl -X POST https://api.truthlocks.com/v1/risk/ato/evaluate \ -H "X-API-Key: tl_live_..." \ -H "Content-Type: application/json" \ -d '{ "subject_id": "user_abc123", "event_type": "login.failed", "ip_address": "198.51.100.42" }' ``` ```javascript JavaScript theme={null} const response = await fetch("https://api.truthlocks.com/v1/risk/ato/evaluate", { method: "POST", headers: { "X-API-Key": "tl_live_...", "Content-Type": "application/json", }, body: JSON.stringify({ subject_id: "user_abc123", event_type: "login.failed", ip_address: "198.51.100.42", }), }); const result = await response.json(); ``` ```python Python theme={null} import httpx resp = httpx.post( "https://api.truthlocks.com/v1/risk/ato/evaluate", headers={"X-API-Key": "tl_live_..."}, json={ "subject_id": "user_abc123", "event_type": "login.failed", "ip_address": "198.51.100.42", }, ) result = resp.json() ``` The response tells you the current risk posture and whether an alert was triggered: ```json theme={null} { "subject_id": "user_abc123", "subject_type": "user", "risk_level": "elevated", "risk_score": 50, "failed_login_count": 5, "alert": true, "alert_type": "velocity_exceeded", "signal_id": "9f3a1c2d-...", "event_type": "login.failed" } ``` ## Threshold rules The platform assigns a risk level based on the number of failed logins within a one-hour rolling window: | Failed logins (1 h window) | Risk level | Risk score | Alert type | | :- | :- | :- | :- | | 0–4 | `normal` | 10 | — | | 5–9 | `elevated` | 50 | `velocity_exceeded` | | 10–19 | `high` | 70 | `velocity_exceeded` | | 20+ | `critical` | 90 | `credential_stuffing` | When a threshold is crossed: 1. An **alert** is created in the ATO alerts table 2. A **risk signal** is automatically ingested with `signal_type: "ato"` and the corresponding score 3. The response includes `alert: true`, the `alert_type`, and the `signal_id` ## Event types | Event type | Behavior | | :- | :- | | `login.failed` | Increments the failed login counter | | `login.failed.repeated` | Increments the failed login counter | | `login.success` | Resets the failed login counter for the subject | | `login.new_device` | Evaluates the event and records the new device in the profile | ## Checking a subject's risk profile Retrieve the current ATO risk profile for a subject without triggering a new evaluation: ```bash theme={null} curl https://api.truthlocks.com/v1/risk/ato/profile/user_abc123 \ -H "X-API-Key: tl_live_..." ``` The profile includes the current risk level, failed login count, and lists of known IP addresses and devices associated with the subject. ## Listing alerts Query ATO alerts for your tenant, optionally filtered by subject: ```bash theme={null} curl "https://api.truthlocks.com/v1/risk/ato/alerts?subject_id=user_abc123&limit=10" \ -H "X-API-Key: tl_live_..." ``` Each alert includes the subject, alert type, risk level at the time of triggering, and a reference to the auto-ingested risk signal. ## Integration patterns ### Block or challenge on elevated risk Use the `risk_level` from the evaluate response to decide whether to allow, challenge, or block a login: ```javascript theme={null} const result = await evaluateATO(subjectId, "login.failed", ipAddress); if (result.risk_level === "critical") { await lockAccount(subjectId); await notifySecurityTeam(result); } else if (result.risk_level === "high") { await requireMFA(subjectId); } else if (result.risk_level === "elevated") { await addCaptchaChallenge(subjectId); } ``` ### Combine with event normalization ATO evaluation can complement the [event normalization pipeline](/guides/risk-signals#event-normalization). Use event normalization for broad risk scoring across all identity events, and ATO evaluation for focused account takeover monitoring with threshold-based alerts. ### Combine with velocity scoring ATO detection focuses on login-based account takeover patterns with built-in threshold rules and alert management. [Velocity scoring](/guides/velocity-scoring) tracks any action type across multiple rolling time windows (1 m, 5 m, 1 h, 24 h) with weighted burst detection. Use both together for layered protection: * **ATO detection** for focused login security — failed login velocity, credential stuffing alerts, subject risk profiles * **Velocity scoring** for general abuse detection — API rate abuse, transaction flooding, registration spam, or any custom action type Both produce risk signals in the same [unified pipeline](/guides/risk-signals), so you can query and review all signals from one place. ### Monitor via webhooks Configure a [webhook endpoint](/guides/webhooks) to receive real-time notifications when ATO alerts are created, so your security team can respond without polling. ## What's next * [Evaluate ATO risk API reference](/api-reference/risk/ato-evaluate) * [Get ATO profile API reference](/api-reference/risk/ato-profile) * [List ATO alerts API reference](/api-reference/risk/ato-alerts) * [Risk signals guide](/guides/risk-signals) * [Velocity and anomaly scoring guide](/guides/velocity-scoring) * [Deepfake and impersonation detection guide](/guides/deepfake-detection) # Business-to-consumer credential delivery Source: https://docs.truthlocks.com/guides/b2b2c Mint, deliver, and verify a consumer credential without confusing the operations. A business first mints a signed attestation, then delivers a reference to a consumer. Delivery does not mint the attestation, verify its claims, or make private records public. ## 1. Mint Follow the [quickstart](/quickstart) using the business workspace's issuer and signing key. Provide application claims through structured `schema` and `claims` input, or encode the exact original bytes as `payload_b64url`. Do not combine both modes. Keep the returned `attestation_id`; do not substitute a made-up `att_` identifier where the API requires a UUID. ## 2. Deliver Use [Deliver to inbox](/api-reference/consumer/deliver) with `attestation_id`, the recipient's email in `consumer_reference`, and optional `safe_metadata`. Use an issuer credential for the workspace owning the attestation. HTTP 201 records delivery to an existing consumer inbox. HTTP 202 with `status: pending` and `reason: consumer_not_registered` records a pending delivery. Neither response proves an email reached the recipient. Avoid sensitive claims in display metadata. ## 3. Read the inbox The consumer authenticates separately and uses [Inbox](/api-reference/consumer/inbox). `read_state` accepts `UNREAD`, `READ`, `ARCHIVED`, or `ALL`. A business key must not be used as the consumer's identity. Inbox delivery and public portfolio visibility are separate. Do not assume an inbox item was publicly shared merely because delivery succeeded. ## 4. Verify Use [Verify](/api-reference/verify) with the attestation ID, and optionally the original encoded payload or document hash. This endpoint does not accept a base64 `proof_bundle` field. Inspect the verdict and reasons rather than HTTP status alone. For offline proofs, follow the [proof bundle specification](/specification/proof-bundle). Offline cryptographic validation needs trusted public keys and cannot establish current revocation status without fresh status information. Neither online nor offline signature verification proves the underlying real-world claim is true. # Embeddable badges Source: https://docs.truthlocks.com/guides/badges Add verification badges to your website, README, or portfolio to prove content authenticity. After you protect content on Truthlocks, you can embed a badge that links to the cryptographic proof. Visitors click the badge to verify authenticity without needing a Truthlocks account. ## How badges work Each protection generates a unique badge URL and a proof page URL. The badge is a dynamic SVG image that shows the current verification status — **Protected** (cyan/green) or **Not Found** (red). Clicking the badge opens the proof page where anyone can inspect the attestation details. Badge URL format: ```text theme={null} https://verify.truthlocks.com/api/badge/{attestation_id} ``` Proof page URL format: ```text theme={null} https://verify.truthlocks.com/proof/{attestation_id} ``` ## Badge styles Badges are available in four styles. Append the `style` query parameter to choose a layout: | Style | Description | Size | | :- | :- | :- | | **default** | Two-tone shield badge with a gradient overlay and rounded corners | 300 × 36 px | | **flat** | Same two-tone layout without gradients — clean and minimal | 300 × 36 px | | **large** | Card-style badge showing status pill, content title, and protection date | 400 × 80 px | | **minimal** | Text-only checkmark label with no background | 200 × 24 px | ```text theme={null} https://verify.truthlocks.com/api/badge/{attestation_id}?style=default https://verify.truthlocks.com/api/badge/{attestation_id}?style=flat https://verify.truthlocks.com/api/badge/{attestation_id}?style=large https://verify.truthlocks.com/api/badge/{attestation_id}?style=minimal ``` ### Dark theme variant Every style supports a dark theme variant. Append `theme=dark` to use lighter backgrounds and brighter accent colors suited for dark-background pages: ```text theme={null} https://verify.truthlocks.com/api/badge/{attestation_id}?style=flat&theme=dark ``` > [!TIP] > > Use the `large` style on landing pages where you want to highlight the protection date and content title. Use `minimal` for inline text or README footers where space is limited. ## Embed formats After protecting content, copy the badge embed code from the proof page or the success screen. Truthlocks provides two formats: ```md Markdown theme={null} [![Protected by Truthlocks](https://verify.truthlocks.com/api/badge/ATTESTATION_ID)](https://verify.truthlocks.com/proof/ATTESTATION_ID) ``` ```html HTML theme={null} Protected by Truthlocks ``` Replace `ATTESTATION_ID` with the ID returned when you minted the protection. To use a specific style, add `?style=flat` (or any style name) to the badge URL. Add `&theme=dark` for dark pages. > [!TIP] > > On the Protect page, click **Copy Badge** after protecting content to copy the > Markdown embed code to your clipboard. ## Dynamic status Badges reflect the real-time verification status of the underlying attestation: | Status | Appearance | Meaning | | - | - | - | | **Protected** | Cyan/green badge | The attestation exists and is valid on the transparency log | | **Not Found** | Red badge | The attestation was not found or has been revoked | Badge responses are cached for up to one hour. If you revoke an attestation, the badge updates to "Not Found" after the cache expires. ## Certificates You can download a formal SVG certificate for any protection. The redesigned certificate features a premium layout with a dark gradient header, circular verification seal, corner ornaments, and a details card showing the category, date, attestation ID, issuer, and SHA-256 content hash. ```text theme={null} GET /api/certificate/{attestation_id} → SVG download GET /api/certificate/{attestation_id}?format=html → HTML view ``` The SVG version downloads as a file (`truthlocks-certificate-{id}.svg`). The HTML version renders the certificate in a centered page layout suitable for printing or embedding. Certificates are useful for legal evidence, portfolio displays, or print. Download them from the proof page or the protection success screen. ## Where to use badges * **GitHub READMEs** — prove authorship of open-source code * **Personal websites** — show visitors your content is verified * **Portfolio pages** — link each piece to its cryptographic proof * **Social media bios** — share your proof page URL directly ## Next steps > **[Content protection](/guides/content-protection)** > > Full guide to protecting content with cryptographic attestations. > **[Public portfolio](/guides/portfolio)** > > Showcase your protected content on a public profile page. > **[Proof bundle spec](/specification/proof-bundle)** > > Technical specification for the verification payload behind each badge. # Code Authorship Protection Source: https://docs.truthlocks.com/guides/code-authorship Prove you wrote the code with cryptographic attestations. Prove you wrote the code. Truthlocks creates cryptographic attestations for source code, APIs, documentation, and other digital assets. Protect your intellectual property with SHA-256 hashing and timestamped proof — all without your source code ever leaving your machine. ## Why Code Authorship Matters * **IP disputes:** Prove you wrote the code before someone else claims it. Timestamped cryptographic proof is admissible evidence. * **Open source protection:** Protect your contributions before publishing. If someone forks and claims ownership, you have proof. * **Contract work:** Prove delivery dates and authorship to clients with independently verifiable attestations. * **Portfolio verification:** Prospective employers or clients can verify your claimed work is genuinely yours. ## How It Works **1. Hash your code locally** Compute SHA-256 of your source file, repository archive, or any artifact. The file content never leaves your machine. **2. Submit the hash** Send the hash, title, and metadata to the Truthlocks API. An attestation is created with your personal signing key. **3. Anchor to transparency log** The attestation is anchored to an append-only, RFC 6962-compatible transparency log with an immutable timestamp. **4. Share the proof** Get a shareable proof URL, embeddable badge, or downloadable certificate. ## Protect a Single File (CLI / API) Hash a source file and submit the attestation: ```bash theme={null} # Hash a file locally (macOS/Linux) HASH=$(sha256sum main.go | awk '{print $1}') # Submit to Truthlocks API curl -X POST https://api.truthlocks.com/v1/consumer/mint \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "content_hash": "'$HASH'", "title": "main.go — Core Engine v2.1", "description": "Primary application entry point and engine logic", "file_name": "main.go", "content_type": "code", "category": "source_code", "visibility": "public" }' ``` ## Protect an Entire Repository Create a deterministic archive of your repo and hash it: ```bash theme={null} # Create a deterministic git archive git archive --format=tar HEAD | sha256sum | awk '{print $1}' # Or hash a specific commit git archive --format=tar | sha256sum | awk '{print $1}' ``` > [!TIP] > > Use `git archive` instead of zipping the directory — it produces deterministic > output regardless of filesystem metadata, making the hash reproducible. ## Examples ```javascript Node.js theme={null} import { createHash } from 'crypto'; import { readFileSync } from 'fs'; // Hash a source file const content = readFileSync('src/index.ts'); const hash = createHash('sha256').update(content).digest('hex'); // Submit to Truthlocks const response = await fetch('https://api.truthlocks.com/v1/consumer/mint', { method: 'POST', headers: { 'Authorization': 'Bearer ' + token, 'Content-Type': 'application/json', }, body: JSON.stringify({ content_hash: hash, title: 'src/index.ts — API Server', description: 'Main API server entry point', content_type: 'code', category: 'source_code', }), }); const { attestation_id, content_hash, protected_at, verify_url } = await response.json(); console.log('Proof URL:', verify_url); console.log('Hash:', content_hash, 'Protected at:', protected_at); ``` ```go Go theme={null} package main import ( "crypto/sha256" "encoding/hex" "fmt" "os" ) func hashFile(path string) (string, error) { data, err := os.ReadFile(path) if err != nil { return "", err } h := sha256.Sum256(data) return hex.EncodeToString(h[:]), nil } func main() { hash, err := hashFile("main.go") if err != nil { panic(err) } fmt.Printf("SHA-256: %s\n", hash) // Submit hash to POST /v1/consumer/mint } ``` ```python Python theme={null} import hashlib import requests def hash_file(path: str) -> str: with open(path, "rb") as f: return hashlib.sha256(f.read()).hexdigest() file_hash = hash_file("app.py") response = requests.post( "https://api.truthlocks.com/v1/consumer/mint", headers={ "Authorization": f"Bearer {token}", "Content-Type": "application/json", }, json={ "content_hash": file_hash, "title": "app.py — Flask Application", "content_type": "code", "category": "source_code", }, ) data = response.json() print(f"Proof: {data['verify_url']}") print(f"Hash: {data['content_hash']} Protected at: {data['protected_at']}") ``` ## CI/CD Integration Automate code protection in your CI pipeline. Protect every release: ```yaml GitHub Actions theme={null} - name: Protect release artifact run: | HASH=$(sha256sum dist/app.tar.gz | awk '{print $1}') curl -X POST https://api.truthlocks.com/v1/consumer/mint \ -H "Authorization: Bearer $TRUTHLOCKS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "content_hash": "'$HASH'", "title": "Release build", "description": "Production release artifact", "content_type": "code", "category": "release" }' ``` ## Add a Badge to Your README Show verification status directly in your repository: ```md Markdown theme={null} [![Protected by Truthlocks](https://verify.truthlocks.com/badge/ATTESTATION_ID)](https://verify.truthlocks.com/proof/ATTESTATION_ID) ``` The badge dynamically shows verification status and is cached for performance. Replace `ATTESTATION_ID` with the ID returned from the mint endpoint. ## Verification Anyone can independently verify your code authorship: 1. Hash the original file with SHA-256 (same algorithm used during protection). 2. Visit the proof URL or call `POST /v1/verify` with the attestation ID. 3. The system confirms the hash matches, verifies the cryptographic signature, and checks the transparency log anchor. ```bash theme={null} # Verify an attestation curl -X POST https://api.truthlocks.com/v1/verify \ -H "Content-Type: application/json" \ -d '{"attestation_id": "b2c3d4e5-..."}' ``` ## Security properties and limits Hashing a file locally can avoid uploading its source bytes, but it is not a zero-knowledge proof. Inspect the chosen client and request to confirm which metadata it sends. An attestation can bind a submitted hash to a signing key and a log checkpoint. That is evidence of the recorded submission; it does not establish who originally wrote the code, exclusive authorship, ownership, or that only one person could have submitted it. Verification depends on trusted keys and the proof material being available. # Audit exports for compliance review Source: https://docs.truthlocks.com/guides/compliance-exports Collect recorded events without assuming a framework certification. Use an audit export as input to your review. The current export API does not accept a `report_type` that automatically produces SOC 2, GDPR, or HIPAA certification. ## Request an export Use [Request audit export](/api-reference/audit/export) with `format`, `from_ts`, `to_ts`, and optional `filter`. Workspace policy must permit export and export storage must be available. Use timestamps for the range; `start_date` and `end_date` are not the current field names. ## Check completion Save the returned export identifier, inspect the job state, and download only after completion. Acceptance is not proof that a file was generated. Failed jobs require attention rather than being treated as empty evidence. ## Interpret the evidence Audit records describe recorded platform activity. They do not prove every external action occurred, that all relevant evidence was collected, or that a regulation's controls were satisfied. Document missing records and review the underlying controls separately. For an aggregation of recorded MAIP compliance checks, use [Generate compliance report](/api-reference/machine-identity/compliance/reports). A signed-in reviewer is required; the result remains a summary of submitted checks. # Compliance review Source: https://docs.truthlocks.com/guides/compliance-review Submit compliance evidence and track the review process for your Truthlocks tenant. Truthlocks may request compliance evidence from your organization as part of ongoing trust and governance requirements. The compliance review workflow lets you view requirements, submit evidence, and track the review status — all from the console. ## Workflow overview The compliance review follows a four-stage process: **1. Requested** Truthlocks sends a compliance request to your tenant. You receive an email notification with the requirements and a deadline. **2. In progress** You review the requirements and prepare your response. Upload evidence documents or provide URLs, then write your answers. **3. Submitted** After you submit, your response is under review. You cannot edit your submission during this stage. **4. Reviewed** The review is complete. Your submission is either approved, declined, or returned with a request for additional information. ## Submitting a compliance response Navigate to **Settings > Compliance** in the console to view any active compliance request. **1. Review requirements** Read the compliance requirements sent by Truthlocks. A deadline is displayed if one has been set. **2. Prepare your answers** Write your response in the answers field. This is a free-text area where you can address each requirement. **3. Attach evidence** Attach supporting documents in one of two ways: * **Upload files** — drag and drop or browse to upload documents directly. * **Add URLs** — paste links to externally hosted documents. **4. Confirm and submit** Check the attestation checkbox to confirm that all information is accurate and complete, then click **Submit**. > [!WARNING] > > You must check the attestation checkbox before submitting. This confirms that > the information you provided is accurate to the best of your knowledge. ## Review outcomes After submission, the platform reviews your response and returns one of three outcomes: | Outcome | What happens next | | :- | :- | | **Approved** | Your compliance status is updated. No further action is needed. | | **Declined** | The review was not accepted. Review the reviewer's notes for details. | | **More info required** | The reviewer needs additional information. Your submission returns to the "In progress" stage so you can update your answers and resubmit. | Reviewer notes are shared with you at each stage so you can understand exactly what is needed. ## Status reference | Status | Description | | :- | :- | | No active request | No compliance review has been requested for your tenant. | | Action required | A request is pending and waiting for your response. | | Under review | Your response has been submitted and is being reviewed. | | Approved | Your compliance evidence has been accepted. | | Declined | Your compliance evidence was not accepted. | | More info needed | The reviewer has requested additional information. | ## Email notifications You receive email notifications at key points in the workflow: * When a compliance request is sent to your tenant * When additional information is requested * When your submission is approved or declined ## Related > **[Audit logs](/security/audit)** > > All compliance actions appear in your audit trail. > **[Trust & compliance](/trust/compliance)** > > Truthlocks platform compliance certifications. # Console onboarding Source: https://docs.truthlocks.com/guides/console-onboarding Set up your organization, issuer, and signing keys with the guided onboarding wizard. When you first sign in to [console.truthlocks.com](https://console.truthlocks.com), a guided wizard walks you through everything you need to start issuing attestations. The wizard detects your progress automatically — if you leave and come back, it picks up where you left off. ## Prerequisites * A Truthlocks account. [Sign up](https://console.truthlocks.com/auth/sign-up) if you do not have one yet. ## Onboarding steps **1. Tenant profile** Enter your organization's basic information: * **Name** — your organization's display name. * **Slug** — a URL-friendly identifier used in API paths and your console URL. * **Contact email** — the primary email for platform communications. * **Country** — where your organization is based (used for data residency). This information is saved to your tenant record and can be updated later from **Settings > Organization**. **2. Organization** Create or select an organization within your tenant. Organizations let you group issuers, users, and attestations under a single entity. Enter: * **Organization name** — the legal or operating name of the organization. If your tenant already has an organization, this step is skipped automatically. **3. Team invites** Invite team members by email and assign them a role: | Role | Permissions | | :- | :- | | Admin | Full access to all tenant resources, settings, and team management | | Member | Create and manage issuers, mint attestations, view audit logs | | Viewer | Read-only access to issuers, attestations, and audit logs | You can skip this step and invite team members later from the **Team** settings page. **4. Issuer profile** Create your first issuer — the entity that signs attestations on behalf of your organization: * **Legal name** — the issuer's registered legal name. * **Display name** — the name shown on attestations and proof pages. * **Website** — the issuer's public website URL. * **Contact email** — used for trust registry verification. The issuer is created at assurance level L1 (basic). You can request a higher assurance level after onboarding by submitting compliance documentation. If your tenant already has an issuer configured, this step is skipped. **5. Signing keys** Generate an Ed25519 signing key for your issuer. This key is used to cryptographically sign every attestation your issuer creates. Click **Generate keys** and the wizard creates a key pair automatically. The public key is registered with the Truthlocks platform, while the private key is stored securely in the signing service. > [!WARNING] > > Signing keys cannot be deleted once generated. If a key is compromised, use the [key compromise](/api-reference/issuers/keys-compromise) endpoint to mark it as compromised and rotate to a new key. If your issuer already has signing keys, this step shows the existing key details and lets you proceed. **6. Test mint** Verify your setup by minting a test attestation. The wizard provides a searchable list of attestation schemas organized into categories: * **Identity** — email verification, KYC, government ID * **Employment** — employment verification, background check, income * **Education** — degree, transcript, enrollment * **Healthcare** — license, immunization, insurance * **Compliance** — SOC2, ISO 27001, GDPR * **Financial** — accreditation, bank verification, credit * **Skills** — certification, assessment, portfolio * **Supply chain** — origin, quality, shipment * **Other** — custom claims Select a schema, enter a recipient email address, and click **Mint test attestation**. The wizard calls the attestation mint endpoint and shows you the resulting attestation ID on success. > [!TIP] > > The test attestation is a real attestation recorded on the transparency log. You can verify it immediately using the [verify endpoint](/api-reference/verify). **7. Go live** The final step shows a checklist of prerequisites: * Tenant profile completed * Organization created * Issuer profile configured * Pipeline verified (test attestation minted) When all items are checked, click **Activate & go to console** to complete onboarding and access the full console dashboard. ## After onboarding Once the wizard is complete, you land on the tenant console dashboard. ### Tenant dashboard The dashboard displays four stat cards at the top: | Card | What it shows | | :- | :- | | **Active issuers** | Trusted issuers out of total configured | | **Attestations** | Total attestations with active or revoked count | | **Active attestations** | Currently valid attestations | | **Roles configured** | System and custom roles | When you have at least one attestation, three insight charts appear below the stat cards: * **Attestation status** — a donut chart breaking down active, revoked, and other attestations. * **Issuer coverage** — a bar chart comparing active issuers versus total issuers. * **Platform health** — a radial gauge showing the percentage of attestations that are currently active. If your organization has a pending compliance request, a banner appears at the top of the dashboard with the requirements and deadline. Click **Review & Submit** to go to the compliance settings page. A **Quick Actions** section provides shortcuts to manage issuers, view attestations, and manage API keys. From the dashboard you can also: * Mint attestations at scale via the console UI or [API](/api-reference/attestations/mint). * Configure [webhooks](/guides/webhooks) to receive real-time event notifications. * Set up [governance policies](/api-reference/governance/create-request) for multi-party approval workflows. * Manage [API keys](/api-reference/api-keys/create) for programmatic access. ## Dark mode The console supports dark mode across all pages. You can switch between three appearance modes from the top bar: | Mode | Behavior | | :- | :- | | **Light** | Light backgrounds with dark text | | **Dark** | Dark backgrounds with light text, optimized for low-light environments | | **System** | Automatically matches your operating system's appearance preference | Click the theme toggle icon in the top bar to cycle through the modes — sun (light), moon (dark), and monitor (system). You can also switch themes from the profile menu — click your avatar in the top-right corner to open a dropdown with light, dark, and system buttons. Your preference is saved locally and persists across sessions. > [!TIP] > > The console defaults to dark mode on first load. The verify portal has its own independent theme setting — see the [consumer portal guide](/guides/consumer-portal#dark-mode). ## Console navigation The console uses a collapsible navigation rail on the left side of the screen: * **Collapsed state** — a narrow rail showing only icons. Hover over it to expand and reveal labels. * **Expanded state** — the full sidebar with icons and page names. Click the pin icon to lock it open. * **Mobile** — on smaller screens, navigation is accessible through a hamburger menu that opens a slide-out drawer. The rail organizes pages into groups — your dashboard, issuers, attestations, verification, API keys, audit logs, and settings. The active page is highlighted, and each group collapses independently. The top bar displays breadcrumbs for your current location, a search shortcut, the [environment switcher](/environments#switching-environments), the theme toggle, and a profile menu. ### Search palette Press `Cmd+K` (macOS) or `Ctrl+K` (Windows/Linux) to open the search palette, or click the search bar in the top bar. The palette lets you jump to any page in the console without navigating through menus. Results include every page available to your role — dashboard, issuers, attestations, verification packs, audit logs, settings, and more. Start typing to filter the list, then press **Enter** to navigate to the selected page. > [!TIP] > > The search shortcut works from anywhere in the console. It is the fastest way to switch between pages when you already know where you want to go. ### Profile menu Click your avatar in the top-right corner to open the profile menu. The avatar displays the first letter of your organization name against a gradient background. The dropdown is organized into three sections: * **Account info** — your organization name and email address. * **Account settings** — opens the security settings page where you can manage your password, sessions, and MFA preferences. * **Theme switcher** — three inline buttons for light, dark, and system themes. The active theme is highlighted. This is an alternative to the theme toggle icon in the top bar. * **Sign out** — logs you out of the console. A confirmation dialog appears before the session ends to prevent accidental sign-outs. ## Announcements The **Announcements** page displays platform-wide messages from Truthlocks — including system updates, security alerts, and operational notifications. Access it from the sidebar under **Announcements**. Each announcement has a priority level: | Priority | When it is used | | :- | :- | | **Normal** | General platform updates and informational messages | | **Urgent** | Time-sensitive changes that may affect your workflows | | **Critical** | Security alerts or service disruptions that require immediate attention | The announcements page uses a master-detail layout: * **Left panel** — a searchable, filterable list of all announcements. Filter by **All**, **Unread**, or **Important** (urgent and critical only). Unread messages show a blue dot indicator. * **Right panel** — the full content of the selected announcement, including the priority badge, timestamp, and sender details. Click an announcement to view it and automatically mark it as read. Use the **Mark all read** button to dismiss all unread indicators at once. ## Related > **[Quick start](/quickstart)** > > Issue your first attestation via the API in under 5 minutes. > **[Core concepts](/concepts)** > > Understand tenants, issuers, attestations, and verification. > **[Environments](/environments)** > > Sandbox vs. production environment configuration. > **[RBAC](/security/rbac)** > > Role-based access control and permission management. # Your personal workspace Source: https://docs.truthlocks.com/guides/consumer-portal Register files, inspect records, manage account access, and understand what each action does. [Truthlocks Verify](https://verify.truthlocks.com) has two parts: a public checker for shared records and a personal workspace for your account. Checking a record is different from registering one. A registration records submitted evidence; it does not independently establish authorship, ownership, identity, or the truth of a claim. ## Find your way around The workspace uses a labeled sidebar with grouped pages and navigation search. You can collapse it on desktop or open the navigation menu on mobile. The top bar shows your location and appearance controls. Choose light, dark, or system appearance. Forms open on their own pages. Read the explanation, enter the details, review the effect, and confirm before submitting. A service error stays visible; it is not a successful change. | Page | What you can do | | - | - | | Dashboard | Review registered-record totals, recent records, and recent inbox entries. Unavailable data is labeled rather than counted as zero. | | Register your work | Select a file, compute its SHA-256 fingerprint in the browser, review metadata and visibility, and submit registration. | | Your collection | Search records, inspect saved details, and open a dedicated visibility form. | | Inbox and history | Review issuer deliveries and explicitly mark an entry read or archive it. Opening an entry does not automatically mark it read. | | Saved records | Review saved snapshots and remove entries from your saved list. A saved snapshot is not a current verification result. | | Disputes | Submit a report about a record and follow its review history. A report does not automatically revoke a record or issue a refund. | | Profile | Edit your display name and manage the public collection address. | | Security | Change your password and configure an authenticator or recovery codes. | | Settings | Review API keys, registered devices, connected applications, billing, and preferences. | | Privacy | Download an account snapshot and track requests for assisted account deletion. | ## Register and check a file Open [Register your work](https://verify.truthlocks.com/protect). Select a file up to the limit shown on the page. The browser computes its fingerprint; keep the original file yourself. AI assistance is optional. If you enable it for a supported file, review the preview and consent before sending extracted content for analysis. Check the suggested title and description yourself. Choosing AI assistance is not an identity or authenticity check. After registration, open the record details to review the saved fingerprint. Use **Check this record** to request a current verification result. A record-details page or downloadable record summary alone is not that result. ## Choose what to share Each record has descriptive visibility. Public titles and descriptions can appear on shared record pages and your public collection. Private descriptions stay in your collection, while the signed record identifier and available integrity evidence can still be checked by ID. Manage your public handle from **Profile → Public collection**. See the [public collection guide](/guides/portfolio) for changing or disabling its address. Changing visibility cannot recall copies someone else already saved. ## Protect account access **Security → Authenticator** supports Google Authenticator and other compatible time-based code apps. Setup requires your current password and a valid code from the newly configured app. Save the recovery codes securely; they are single-use alternatives to app codes. API keys are shown in full only when created. Revoke a key you no longer need. Device registrations and application authorizations have separate removal pages. Removing a device registration does not terminate browser sessions. > [!NOTE] > > Open **Security → Browser sessions** to review up to 100 unexpired sessions observed for your account and sign out other sessions. A confirmed password change keeps the current session and revokes other existing sessions; a password reset revokes prior sessions. Enabling or disabling an authenticator, or replacing recovery codes, revokes all existing browser sessions. Save recovery codes privately and sign in again after the change. ## Manage billing **Settings → Billing** shows the subscription state returned by the billing service. Compare the current personal plans, open a full review page, and confirm before requesting checkout. A checkout link does not prove payment or activation. An existing paid subscription must be managed before another checkout can start. Provider management and cancellation each have a review page. After making a change with the provider, refresh billing to inspect the recorded result. Cancellation does not automatically refund payments or delete your account. ## Download data or request deletion **Privacy → Download account snapshot** prepares a private JSON download from your personal account registry. It includes your profile, preferences, registered-record metadata, inbox, saved records, recorded devices and applications, disputes, and request history. It excludes authentication secrets, original files, signed proof bundles, billing-provider data, and records independently held by an issuer. It is not a complete export from every Truthlocks service. **Request account deletion** records your reason for assisted staff review. Your account is not immediately erased or signed out, and submitting the request does not cancel billing. Repeating a request while one is pending returns the existing request. Automated erasure is not currently available. Fine-grained notification delivery controls are not connected yet. The notification page explains this instead of offering switches that would not change delivery. ## Get help Open **Support** in the workspace, or email [support@truthlocks.com](mailto:support@truthlocks.com). Include the affected page and a record or request ID when relevant. Do not send passwords, API keys, authenticator secrets, or recovery codes. # Register a file record Source: https://docs.truthlocks.com/guides/content-protection Create a signed record of a file fingerprint, review its evidence, and choose which details to share. File registration creates a dated record of a SHA-256 fingerprint and the details you supply. A matching fingerprint can show that two file copies have the same bytes. Registration does not prevent copying, grant copyright, or independently prove authorship or the truth of the file's contents. ## Register in your workspace 1. Sign in at [Truthlocks Verify](https://verify.truthlocks.com/login) and open **Register your work**. 2. Select or drop a file up to **50 MB**. Your browser computes its SHA-256 fingerprint. 3. Enter a title and optional description. Check that the details are accurate and suitable for your chosen visibility. 4. Choose private or public descriptive details. You can check for exact matches among public fingerprints; this is not an originality search. 5. Review and confirm, then submit registration. If the service reports a failure, check your collection before retrying with the same file. The original file is not uploaded for registration. Keep your own copy so you can compare it later. The record stores the fingerprint and supplied metadata, not a backup of the file. ## Optional Gemini suggestions For files up to **10 MB**, **Suggest with Gemini** can use the filename, type and size to suggest a title and description. A separate optional checkbox permits a short text excerpt or basic image metadata to be sent too. Review any suggestions before registering. You can write all details yourself. AI assistance is not required, and its output is not a verification or identity decision. ## Review the result After a successful response, open your collection entry to inspect its fingerprint, record ID and saved details. Use **Check this record** to run a current verification. The public record page and downloadable summary show stored information; they do not replace a current check. Private visibility limits the descriptive details shown publicly. Anyone with a record identifier can still request the available signature, issuer and integrity checks. See [public collections](/guides/portfolio) for sharing selected records under a public handle. ## Register through the API Use a personal-session bearer token. Compute the SHA-256 fingerprint of the complete original file before calling this endpoint. The example fingerprint below represents an empty file; replace it with your file's actual 64-character hexadecimal fingerprint. ```http theme={null} POST /v1/consumer/mint Authorization: Bearer Content-Type: application/json { "content_hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855", "title": "My document", "description": "Details supplied by the account owner.", "file_name": "document.txt", "file_size": 0, "content_type": "text/plain", "category": "document", "visibility": "private" } ``` The service resolves the personal signing identity for the account. A successful result includes the protection ID, attestation ID, content fingerprint, registration time, and record links. Treat an error as an unconfirmed result; do not invent a record URL or assume signing succeeded. Retrying an already registered fingerprint for the same account returns its existing record. It does not update the original descriptive details. Use the record visibility endpoint for a visibility change. The current monthly allowance is checked before creating a new registration. Consult the billing page for the recorded plan and contact support if its capacity is inconsistent. Existing records remain available for inspection when a monthly registration allowance is exhausted. ## Limits of the evidence * A fingerprint comparison concerns file integrity, not whether its claims are true. * A stored registration time is not proof of when the original work was first created. * A personal signing identity is not independent document-based identity verification. * Making a record private cannot recall copies of public details already saved by others. ## Download a readable certificate Open a record’s shareable proof page and choose **Download certificate**. The SVG certificate includes the recorded UTC timestamp, record identifier, available fingerprint and issuer details, and a QR link back to the record. Business Console attestation details and the record checker use the same certificate design. Choose **Print / save as PDF** on the proof page or Console record details, then use your browser’s Print command. The document-generated timestamp is separate from the original recorded timestamp. If the original timestamp is missing from storage, the certificate says so instead of substituting today’s date. A certificate is a readable record summary. For machine verification, download the separate proof bundle and check the available evidence. A certificate does not establish ownership or guarantee that the record remains active. # Cross-Tenant Delegation Source: https://docs.truthlocks.com/guides/cross-tenant-delegation Enable AI agents to operate across organizational boundaries with cryptographic delegation chains. # Cross-Tenant Delegation Cross-tenant delegation allows an agent owned by one organization to perform actions within another organization's Truthlocks tenant — with full audit trails and revocable authorization. ## Use Cases * **Managed service providers** operating agents on behalf of clients * **Supply chain partners** sharing verification data across organizations * **Platform integrators** running agents that span multiple customer tenants * **Consulting firms** performing compliance checks across client environments > [!TIP] > > Delegation endpoints have an interactive API playground. Open the [Guardrails & Delegation](/api-reference/machine-identity/delegations/offer) API reference and click **Send** to try it against the Sandbox. ## How it works ``` ┌──────────────┐ ┌──────────────┐ │ Tenant A │ │ Tenant B │ │ (Delegator) │ │ (Delegate) │ │ │ offer │ │ │ Agent X ────┼────────►│ Agent Y │ │ │ │ (accepts) │ │ │ accept │ │ │ │◄────────┼── │ └──────────────┘ └──────────────┘ │ │ ▼ ▼ delegation_id scoped_token audit_trail limited_ttl ``` ## Delegation Flow ### Step 1: Offer Delegation ```bash theme={null} curl -X POST https://api.truthlocks.com/v1/delegations/cross-tenant/offer \ -H "X-API-Key: $TENANT_A_API_KEY" \ -d '{ "from_agent_id": "maip-agent:01JAAAA", "to_tenant_id": "tenant_B", "scopes": ["receipts:write", "attestations:read"], "constraints": { "max_actions_per_hour": 100, "ip_allowlist": ["10.0.0.0/8"], "expires_at": "2026-05-01T00:00:00Z" }, "require_trust_score_above": 70, "metadata": { "purpose": "Quarterly compliance audit", "approved_by": "admin@tenant-a.com" } }' ``` **Response:** ```json theme={null} { "id": "maip-delegation:01JDDDD", "status": "pending", "from_agent_id": "maip-agent:01JAAAA", "to_tenant_id": "tenant_B", "scopes": ["receipts:write", "attestations:read"], "offer_expires_at": "2026-04-13T00:00:00Z" } ``` ### Step 2: Accept Delegation ```bash theme={null} curl -X POST https://api.truthlocks.com/v1/delegations/cross-tenant/accept \ -H "X-API-Key: $TENANT_B_API_KEY" \ -d '{ "accepting_agent_id": "maip-agent:01JBBBB", "acknowledge_constraints": true }' ``` **Response:** ```json theme={null} { "id": "maip-delegation:01JDDDD", "status": "active", "delegated_token": "mdt_live_...", "effective_scopes": ["receipts:write", "attestations:read"], "expires_at": "2026-05-01T00:00:00Z" } ``` ### Step 3: Execute Cross-Tenant Actions ```bash theme={null} curl -X POST https://api.truthlocks.com/v1/receipts \ -H "Authorization: Bearer mdt_live_..." \ -d '{ "type": "compliance.check.completed", "subject_id": "vendor_456", "payload": { "result": "pass", "checks_run": 12 } }' ``` ## Security Model ### Constraints | Constraint | Description | | - | - | | `max_actions_per_hour` | Rate limit for delegated actions | | `ip_allowlist` | Network restrictions | | `expires_at` | Hard expiration date | | `require_trust_score_above` | Minimum trust score to maintain delegation | | `scopes` | Subset of the delegating agent's scopes | ### Audit Trail All cross-tenant actions generate dual audit entries — one in each tenant's audit log: ```json theme={null} { "event": "delegation.action", "delegation_id": "maip-delegation:01JDDDD", "acting_agent": "maip-agent:01JBBBB", "acting_tenant": "tenant_B", "target_tenant": "tenant_A", "action": "receipts:write", "timestamp": "2026-04-06T14:30:00Z" } ``` ### Revocation Either party can revoke a delegation at any time: ```bash theme={null} curl -X DELETE https://api.truthlocks.com/v1/delegations/maip-delegation:01JDDDD \ -H "X-API-Key: $API_KEY" \ -d '{ "reason": "Engagement concluded" }' ``` Revocation is **immediate** — all in-flight requests using the delegated token are rejected. ## Best Practices 1. **Time-bound all delegations** — Never create open-ended delegations 2. **Minimum viable scopes** — Only delegate the scopes actually needed 3. **Trust score requirements** — Set `require_trust_score_above` to at least 70 4. **IP restrictions** — Always use `ip_allowlist` for production delegations 5. **Monitor delegation activity** — Set up webhooks for `delegation.*` events 6. **Regular review** — Audit active delegations quarterly ## Next steps > **[Agent Authorization](/guides/agent-authorization)** > > Scope-based authorization and session management. > **[AI Orchestration](/guides/ai-orchestration)** > > Multi-agent workflow execution with delegation support. # Custom domains Source: https://docs.truthlocks.com/guides/custom-domains Set up branded URLs for your verification portal and console with custom domain configuration and DNS verification. Custom domains let you serve the Truthlocks verification portal and console from your own domain. Instead of `verify.truthlocks.com`, your users see `verify.yourdomain.com`. > [!NOTE] > > Custom domains are available on all plans. Navigate to **Settings > Domains** > in the console to get started. ## Domain types Truthlocks supports two types of custom domains: | Type | Purpose | Example | | :- | :- | :- | | **Verification** | Public-facing verification portal where recipients and auditors verify attestations | `verify.yourdomain.com` | | **Console** | Administrative console for your team | `console.yourdomain.com` | You can configure one or both types depending on your needs. ## Setting up a custom domain **1. Open domain settings** Navigate to **Settings > Domains** in the console. **2. Add a domain** Click **Add Domain**, select the domain type (Verification or Console), and enter the hostname you want to use (e.g., `verify.yourdomain.com`). **3. Add the DNS record** Truthlocks generates a unique verification token for your domain. Add a TXT record to your DNS configuration: | Field | Value | | :- | :- | | **Type** | `TXT` | | **Name** | `_truthlocks-verify` | | **Value** | The verification token shown in the console | Copy the token using the **Copy** button next to it. **4. Verify the domain** After adding the DNS record, click **Verify DNS Record** in the console. Truthlocks checks for the TXT record and updates the domain status. > [!TIP] > > DNS propagation can take up to 48 hours, though most providers propagate > within minutes. If verification fails, wait a few minutes and try again. ## Domain statuses Each domain progresses through three statuses: | Status | Meaning | | :- | :- | | **Pending** | The domain has been added but the DNS record has not been verified yet. | | **Verified** | The DNS TXT record was found and validated. The domain becomes active automatically. | | **Active** | The domain is live and serving traffic for your tenant. | ## Managing domains via the API You can add, list, and verify custom domains programmatically. ### List domains ```http Request theme={null} GET /v1/settings/domains X-API-Key: tl_live_... ``` ```json Response theme={null} { "domains": [ { "id": "dom_abc123", "tenant_id": "tn_xyz789", "type": "VERIFY", "hostname": "verify.acme.com", "status": "ACTIVE", "verification_token": "tl-verify-abc123def456", "verified_at": "2026-03-25T14:30:00Z", "created_at": "2026-03-25T14:00:00Z" } ] } ``` ### Add a domain ```http Request theme={null} POST /v1/settings/domains X-API-Key: tl_live_... Content-Type: application/json { "type": "VERIFY", "hostname": "verify.acme.com" } ``` The `type` field accepts `VERIFY` for verification domains or `CONSOLE` for console domains. The response includes the `verification_token` you need for DNS setup. ### Verify a domain ```http Request theme={null} POST /v1/settings/domains/{domain_id}/verify X-API-Key: tl_live_... ``` Returns the updated domain object. If the DNS record is not found, the status remains `PENDING`. ## Example: full setup ```bash theme={null} # 1. Add the domain curl -X POST https://api.truthlocks.com/v1/settings/domains \ -H "X-API-Key: tl_live_..." \ -H "Content-Type: application/json" \ -d '{"type": "VERIFY", "hostname": "verify.acme.com"}' # 2. Add the TXT record to your DNS (using your DNS provider) # Name: _truthlocks-verify # Value: # 3. Verify the domain curl -X POST https://api.truthlocks.com/v1/settings/domains/dom_abc123/verify \ -H "X-API-Key: tl_live_..." ``` ## Troubleshooting ### Verification keeps failing 1. Confirm the TXT record name is exactly `_truthlocks-verify` (some providers append the domain automatically — check for duplicates like `_truthlocks-verify.yourdomain.com.yourdomain.com`). 2. Wait for DNS propagation. Use `dig TXT _truthlocks-verify.yourdomain.com` to confirm the record is visible. 3. Ensure the TXT value matches the token shown in the console exactly, with no extra spaces. ### Domain is verified but not active Verified domains transition to Active automatically. If the status does not update, refresh the page or re-fetch via the API. ## Related > **[Custom branding](/guides/enterprise-branding)** > > Upload logos and set brand colors for verification pages and emails. > **[Email delivery](/security/email-delivery)** > > Configure custom email senders and SMTP servers. # Deepfake and impersonation detection Source: https://docs.truthlocks.com/guides/deepfake-detection Evaluate supplied deepfake and impersonation indicators or external scores, and route threshold results into risk signals. > [!WARNING] > > This endpoint does not download or inspect the referenced image, video, or document. It scores indicators or scores supplied by your application. Values are heuristic risk scores, not calibrated probabilities. The `authentic` label means the configured risk threshold was not reached; it is not proof that media is authentic, especially when no indicators were supplied. The deepfake and impersonation API evaluates indicators or external scores supplied by your application for a referenced subject. It does not inspect the referenced media or document. Results that exceed the risk threshold automatically create a [risk signal](/guides/risk-signals), connecting your upstream detection evidence to the Anti-Fraud Identity Firewall pipeline. > [!NOTE] > > Deepfake detection is part of the [Anti-Fraud Identity Firewall](/guides/risk-signals). Scan results flow into the same risk signal pipeline as other fraud signals, so you can query and review them from the **Risk & Fraud > Signals** console page or the [list signals endpoint](/api-reference/risk-signals/list). ## How it works **1. Submit a scan** Send a `POST` request to `/v1/risk/deepfake/scan` with a subject reference and either raw indicator signals from your detection pipeline or pre-computed scores from an external model. **2. Review the verdict** The response includes deepfake and impersonation scores (0–100) and a verdict: `authentic`, `suspect`, `deepfake`, or `impersonation`. **3. Automatic signal creation** When a score reaches 60 or above, the platform automatically ingests a risk signal into your tenant's pipeline. The response includes the `signal_id` so you can trace it. **4. Retrieve results later** Use `GET /v1/risk/deepfake/results/{subject_ref}` to fetch the latest scan result for any previously scanned subject. ## Prerequisites * An active Truthlocks tenant with an API key * Subject references for the content you want to scan (URLs, SHA-256 hashes, attestation IDs, or opaque identifiers) ## Scanning a subject Submit a scan with indicator signals from your detection pipeline: ```bash cURL theme={null} curl -X POST https://api.truthlocks.com/v1/risk/deepfake/scan \ -H "X-API-Key: tl_live_..." \ -H "Content-Type: application/json" \ -d '{ "subject_ref": "sha256:a1b2c3d4...", "subject_type": "image", "signals": ["face_swap_detected", "inconsistent_lighting"] }' ``` ```javascript JavaScript theme={null} const response = await fetch("https://api.truthlocks.com/v1/risk/deepfake/scan", { method: "POST", headers: { "X-API-Key": "tl_live_...", "Content-Type": "application/json", }, body: JSON.stringify({ subject_ref: "sha256:a1b2c3d4...", subject_type: "image", signals: ["face_swap_detected", "inconsistent_lighting"], }), }); const result = await response.json(); ``` ```python Python theme={null} import httpx resp = httpx.post( "https://api.truthlocks.com/v1/risk/deepfake/scan", headers={"X-API-Key": "tl_live_..."}, json={ "subject_ref": "sha256:a1b2c3d4...", "subject_type": "image", "signals": ["face_swap_detected", "inconsistent_lighting"], }, ) result = resp.json() ``` The response includes scores, a verdict, and (if the threshold was met) a linked risk signal: ```json theme={null} { "scan_id": "7c8d9e0f-...", "subject_ref": "sha256:a1b2c3d4...", "subject_type": "image", "deepfake_score": 60, "impersonation_score": 0, "verdict": "suspect", "indicators": ["face_swap_detected", "inconsistent_lighting"], "detection_model": "heuristic_v1", "signal_id": "9f3a1c2d-...", "created_at": "2027-05-22T10:00:00Z" } ``` ## Detection model The platform uses a heuristic signal engine (`heuristic_v1`) that maps caller-provided indicators to weighted scores. The engine evaluates 12 indicators across two categories: ### Deepfake indicators | Indicator | Description | | :- | :- | | `face_swap_detected` | Face replacement or morphing detected | | `inconsistent_lighting` | Lighting inconsistencies across the subject | | `compression_artifacts` | Unusual compression patterns suggesting manipulation | | `temporal_inconsistency` | Frame-level inconsistencies in video content | | `metadata_mismatch` | File metadata doesn't match expected patterns | ### Impersonation indicators | Indicator | Description | | :- | :- | | `biometric_mismatch` | Biometric data doesn't match the claimed identity | | `name_mismatch` | Name on identity document doesn't match records | | `identity_doc_mismatch` | Identity document appears altered or inconsistent | | `issuer_trust_violation` | Issuer trust level is insufficient for the claim | ## Verdicts and thresholds Each scan produces a verdict based on the highest score: | Score range | Verdict | Meaning | | :- | :- | :- | | 0 – 39 | `authentic` | No significant indicators detected | | 40 – 74 | `suspect` | Some indicators present — review recommended | | 75 – 100 | `deepfake` or `impersonation` | High confidence detection — which verdict depends on the dominant score | When either score reaches **60 or above**, the platform automatically creates a risk signal. You don't need to make a separate API call — the `signal_id` is returned in the scan response. ## Using pre-computed scores If you already have scores from an external ML model or detection service, pass them directly to skip heuristic analysis: ```bash theme={null} curl -X POST https://api.truthlocks.com/v1/risk/deepfake/scan \ -H "X-API-Key: tl_live_..." \ -H "Content-Type: application/json" \ -d '{ "subject_ref": "sha256:a1b2c3d4...", "subject_type": "video", "deepfake_score": 82, "impersonation_score": 15 }' ``` The platform still applies the same verdict thresholds and automatic signal ingestion, so you get consistent classification regardless of the detection source. ## Linking scans to attestations Associate a scan with an existing attestation to tie detection results to the credential they relate to: ```bash theme={null} curl -X POST https://api.truthlocks.com/v1/risk/deepfake/scan \ -H "X-API-Key: tl_live_..." \ -H "Content-Type: application/json" \ -d '{ "subject_ref": "sha256:a1b2c3d4...", "subject_type": "attestation", "signals": ["biometric_mismatch", "identity_doc_mismatch"], "attestation_id": "660e8400-e29b-41d4-a716-446655440001" }' ``` This makes it easier to flag and review suspicious attestations in the console. ## Retrieving scan results Fetch the latest scan result for a subject without re-running the scan: ```bash theme={null} curl https://api.truthlocks.com/v1/risk/deepfake/results/sha256:a1b2c3d4... \ -H "X-API-Key: tl_live_..." ``` ## Subject types The `subject_type` field tells the platform what kind of content is being scanned: | Type | Use case | | :- | :- | | `image` | Photos, ID documents, profile pictures | | `video` | Video recordings, live captures | | `document` | PDFs, scanned documents | | `attestation` | Credentials issued through the platform | | `identity` | Identity claims, KYC submissions | ## Usage metering Each deepfake scan request increments the `antifraud.deepfake_scans` usage counter for your billing cycle. You can monitor your scan consumption with the [usage API](/api-reference/billing/usage) or in the console at **Settings > Billing > Usage** under the **Anti-Fraud** section. > [!NOTE] > > Deepfake scan quotas vary by plan tier. See the [billing overview](/billing/overview#metered-products) for details on all Anti-Fraud metered products. ## What's next * [Deepfake scan API reference](/api-reference/risk/deepfake-scan) * [Get scan results API reference](/api-reference/risk/deepfake-results) * [Account takeover detection guide](/guides/ato-detection) * [Velocity and anomaly scoring guide](/guides/velocity-scoring) * [Risk signals guide](/guides/risk-signals) * [Ingest risk signal API reference](/api-reference/risk/ingest-signal) # Custom branding Source: https://docs.truthlocks.com/guides/enterprise-branding Customize your verification pages, emails, and proof bundles with your organization's branding. Enterprise tenants can apply custom branding to verification pages, transactional emails, and proof bundles. Upload your logo, set brand colors, and preview changes before saving. > [!NOTE] > > Custom branding requires a Business or Enterprise plan, or the White-Label > add-on. See [billing](/billing/overview) for plan details. ## Branding settings Navigate to **Settings > Branding** in the console to configure your brand. ### Logo Upload your organization's logo. The logo appears on verification pages, transactional emails, and credential cards. | Requirement | Value | | :- | :- | | Formats | PNG, JPEG, SVG, WebP | | Max file size | 2 MB | ### Brand name Set the name displayed on verification pages and credential cards. This is typically your organization or product name. ### Colors Configure two colors that define your brand appearance: | Color | Where it appears | Default | | :- | :- | :- | | **Primary** | Card headers, primary UI elements | `#06b6d4` | | **Accent** | Badges, tags, secondary highlights | `#0891b2` | Use the color picker or enter a hex value directly (e.g., `#1a2b3c`). ## Live preview The branding page includes a live preview panel that shows how your logo, brand name, and colors appear on a credential card. Changes update in real time as you adjust settings. ## Configuring branding **1. Upload your logo** Click the upload area or drag and drop your logo file. The preview updates immediately. **2. Set your brand name** Enter your organization name in the Brand Name field. **3. Choose your colors** Use the color pickers to set your primary and accent colors, or enter hex values directly. **4. Save** Click **Save Branding** to apply your changes. A confirmation banner appears when the save completes. ## Managing branding via the API You can read and update branding settings programmatically. All write endpoints require the White-Label entitlement. ### Get current branding ```http Request theme={null} GET /v1/settings/branding X-API-Key: tl_live_... ``` ```json Response theme={null} { "tenant_id": "tn_abc123", "brand_name": "Acme Corp", "logo_url": "https://cdn.truthlocks.com/branding/tn_abc123/logo/logo.png", "primary_color": "#10b981", "accent_color": "#059669" } ``` If no branding has been configured, the response returns the default colors (`#06b6d4` primary, `#0891b2` accent) and no logo. ### Update branding Set your brand name and colors in a single request: ```http Request theme={null} PUT /v1/settings/branding X-API-Key: tl_live_... Content-Type: application/json { "brand_name": "Acme Corp", "primary_color": "#10b981", "accent_color": "#059669" } ``` Colors must be valid hex values in `#RRGGBB` format. Omitted fields keep their current values. ### Upload a logo Logo uploads use a three-step presigned URL flow: **1. Request a presigned upload URL** ```http Request theme={null} POST /v1/settings/branding/logo/presign X-API-Key: tl_live_... Content-Type: application/json { "filename": "logo.png", "content_type": "image/png", "size_bytes": 48000 } ``` ```json Response theme={null} { "upload_url": "https://s3.amazonaws.com/...", "s3_key": "branding/tn_abc123/logo/ast_xyz/logo.png", "asset_id": "ast_xyz", "expires_in": 600 } ``` The presigned URL expires after 10 minutes. **2. Upload the file to the presigned URL** Upload your logo directly to the returned `upload_url` using an HTTP PUT request with the file contents as the body. **3. Confirm the upload** ```http Request theme={null} POST /v1/settings/branding/logo/confirm X-API-Key: tl_live_... Content-Type: application/json { "asset_id": "ast_xyz", "s3_key": "branding/tn_abc123/logo/ast_xyz/logo.png" } ``` After confirmation, the new logo appears on all branding surfaces. > [!WARNING] > > Write endpoints (`PUT /v1/settings/branding`, logo presign, and logo confirm) return HTTP 402 if your plan does not include the White-Label entitlement. See [billing](/billing/overview) for plan details. ## Where branding appears Your custom branding is applied across several surfaces: > **Verification pages** > > Public proof pages display your logo and brand colors. > **Transactional emails** > > Emails sent on your behalf (e.g., credential deliveries, team invites) > include your logo. > **Proof bundles** > > Downloaded proof bundles reference your brand name and issuer identity. > **Credential cards** > > The credential card shown to recipients uses your primary color and logo. ## Permissions Updating branding settings requires the `branding.write` permission, which is granted to the **Tenant Admin** and **Org Admin** roles by default. Any authenticated user with `settings.read` can view branding settings. ## Related > **[Billing](/billing/overview)** > > Plan tiers and the White-Label add-on. > **[B2B2C delivery](/guides/b2b2c)** > > How branded credentials are delivered to consumers. > **[Custom domains](/guides/custom-domains)** > > Serve the verification portal and console from your own domain. # Issuance policies Source: https://docs.truthlocks.com/guides/issuance-policies Define rule-based policies that control who can mint, verify, and export attestations in your tenant. Issuance policies let you enforce compliance, jurisdiction, and trust requirements across minting, verification, and proof-bundle exports. When a policy is active, every matching request is evaluated against your rules before it proceeds. Requests that don't match are denied with a clear reason. ## When to use policies Use issuance policies when you need to: * Restrict minting to issuers in specific jurisdictions (e.g., US-only or US and EU) * Require a minimum trust tier before an issuer can create attestations * Enforce different rules for minting vs. verification * Control who can export proof bundles or submit data-portability requests * Test a policy against sample inputs before deploying to production * Audit which policy was in effect when an attestation was created If you don't create any policies, all minting, verification, and export requests are allowed by default. ## How policies work Each policy contains one or more **rules**. A rule has: * **Conditions** — field-level checks evaluated against the request context (e.g., `jurisdiction eq US`) * **Effect** — `ALLOW` or `DENY` if the conditions match * **Default effect** — applied when no rule matches Rules are evaluated in order. The first matching rule determines the outcome. If no rule matches, the `default_effect` applies. ```json theme={null} { "rules": [ { "id": "us_only", "description": "US jurisdiction required", "conditions": [ { "field": "jurisdiction", "op": "eq", "value": "US" } ], "effect": "ALLOW" } ], "default_effect": "DENY" } ``` ### Condition operators | Operator | Description | Example | | - | - | - | | `eq` | Equals | `{ "field": "jurisdiction", "op": "eq", "value": "US" }` | | `neq` | Not equals | `{ "field": "trust_tier", "op": "neq", "value": "individual" }` | | `in` | Matches any value in a list | `{ "field": "trust_tier", "op": "in", "value": ["verified_org", "enterprise"] }` | | `nin` | Does not match any value in a list | `{ "field": "jurisdiction", "op": "nin", "value": ["CN", "RU"] }` | | `gt` | Greater than (numeric) | `{ "field": "key.age_days", "op": "gt", "value": 90 }` | | `lt` | Less than (numeric) | `{ "field": "key.age_days", "op": "lt", "value": 365 }` | | `exists` | Field is present | `{ "field": "jurisdiction", "op": "exists", "value": true }` | Conditions support dot-notation for nested fields (e.g., `key.age_days`, `key.status`). ### Available fields Any field in the evaluation input can be referenced, including nested fields with dot-notation. The following fields are available by default: | Field | Description | | - | - | | `jurisdiction` | The issuer's registered jurisdiction (ISO country code) | | `trust_tier` | The issuer's trust tier (`individual`, `verified_org`, `regulated_issuer`, `enterprise`) | | `status` | The issuer's current status (`ACTIVE`, `suspended`, `revoked`, `SUNSET`, `pending`) | | `risk_rating` | The issuer's risk rating (`low`, `medium`, `high`, `CRITICAL`) | | `assurance_level` | The issuer's assurance level (`standard`, `high`, `regulated`) | | `key.age_days` | Age of the signing key in days | | `key.status` | Status of the signing key (`ACTIVE`, `REVOKED`, `EXPIRED`) | | `key.kid` | Identifier of the signing key | ## Policy lifecycle Each policy has a status that controls whether it is enforced: | Status | Behavior | | - | - | | `DRAFT` | Saved but not enforced — use this while you iterate on rules | | `ACTIVE` | Enforced on every matching request | | `DISABLED` | Temporarily turned off without deleting the policy | When you create a policy you choose the initial status. Only `ACTIVE` policies are evaluated at request time. ### Lifecycle transitions Policies typically follow this progression: 1. **Create as `DRAFT`** — write and refine your rules without affecting live traffic. 2. **Simulate** — test the draft policy against sample inputs using the [policy simulator](#simulating-a-policy). 3. **Activate** — set the status to `ACTIVE` so the policy is enforced on matching requests. 4. **Disable** — set the status to `DISABLED` to temporarily stop enforcement without losing the policy definition. 5. **Delete** — remove the policy entirely when it is no longer needed. You can transition between `DRAFT`, `ACTIVE`, and `DISABLED` at any time by updating the policy. Each status change increments the policy version, which is recorded alongside every evaluation decision for auditability. > [!NOTE] > > Transitioning a policy to `ACTIVE` takes effect immediately. Make sure you have tested the rules with the simulator before activating. ## Policy categories Policies are scoped to a specific action: | Category | Applies to | | - | - | | `MINT` | Attestation minting requests | | `VERIFY` | Verification requests | | `BUNDLE_EXPORT` | Proof-bundle export and data-portability requests | You can have multiple active policies. Each policy applies only to its category. ### Export control policies `BUNDLE_EXPORT` policies control who can export proof bundles and submit data-portability requests. Use them to restrict exports by jurisdiction, trust tier, or any other field in the evaluation input. ```json theme={null} { "rules": [ { "id": "block_non_enterprise", "description": "Only enterprise-tier issuers can export bundles", "conditions": [ { "field": "trust_tier", "op": "nin", "value": ["enterprise", "regulated_issuer"] } ], "effect": "DENY" }, { "id": "allow_low_risk", "description": "Allow exports for low-risk issuers", "conditions": [ { "field": "risk_rating", "op": "eq", "value": "low" } ], "effect": "ALLOW" } ], "default_effect": "DENY" } ``` To create this policy via the API, set `category` to `BUNDLE_EXPORT`: ```bash theme={null} curl -X POST https://api.truthlocks.com/v1/policies \ -H "X-API-Key: tl_live_..." \ -H "Content-Type: application/json" \ -d '{ "name": "Enterprise Export Only", "category": "BUNDLE_EXPORT", "status": "ACTIVE", "description": "Restrict proof-bundle exports to enterprise issuers with low risk", "language": "json_rules", "rules": { "rules": [ { "id": "block_non_enterprise", "description": "Only enterprise-tier issuers can export bundles", "conditions": [ { "field": "trust_tier", "op": "nin", "value": ["enterprise", "regulated_issuer"] } ], "effect": "DENY" } ], "default_effect": "ALLOW" } }' ``` ### Policy bindings Policy bindings connect a policy to a specific target so the engine knows when to apply it. Each binding includes: | Field | Type | Description | | - | - | - | | `policy_id` | string | The ID of the policy to bind | | `target_type` | string | `ISSUER`, `VERIFICATION_PROFILE`, or `TENANT_DEFAULT` | | `target_id` | string | UUID of the target. Omit for `TENANT_DEFAULT` to apply the policy to all entities. | | `action` | string | `MINT`, `VERIFY`, or `BUNDLE_EXPORT` | | `priority` | integer | Higher-priority bindings are evaluated first | When multiple bindings match a request, they are evaluated in descending priority order. The first `DENY` result stops evaluation immediately. #### Creating a binding via the API ```bash theme={null} curl -X POST https://api.truthlocks.com/v1/policies/bindings \ -H "X-API-Key: tl_live_..." \ -H "Content-Type: application/json" \ -d '{ "policy_id": "pol_abc123", "target_type": "ISSUER", "target_id": "iss_def456", "action": "MINT", "priority": 100 }' ``` To apply a policy as the tenant-wide default, set `target_type` to `TENANT_DEFAULT` and omit `target_id`: ```bash theme={null} curl -X POST https://api.truthlocks.com/v1/policies/bindings \ -H "X-API-Key: tl_live_..." \ -H "Content-Type: application/json" \ -d '{ "policy_id": "pol_abc123", "target_type": "TENANT_DEFAULT", "action": "MINT", "priority": 10 }' ``` > [!TIP] > > Use higher priority values for more specific bindings. For example, assign priority `100` to an issuer-level binding and `10` to the tenant default so the issuer-specific policy is evaluated first. ## Creating a policy ### From the console 1. Go to **Policies** in the console sidebar 2. Click **Create policy** 3. Enter a name, select a category (`MINT`, `VERIFY`, or `BUNDLE_EXPORT`), and choose a status 4. Write your rules in JSON format or use a template 5. Click **Deploy Policy** — if the status is `ACTIVE`, it takes effect immediately ### From a template The console includes four ready-to-use templates you can add with one click: | Template | Category | Description | | - | - | - | | Allow US Jurisdiction | MINT | Only allow minting from US-based issuers | | Verified Org Only | MINT | Require `verified_org` trust tier or higher | | Allow All (Permissive) | MINT | Allow all mints — use with caution | | Verify - US & EU Only | VERIFY | Only accept verifications from US or EU jurisdictions | To use a template, open the **Templates** tab on the policies page and click **Use template**. The policy is created and activated immediately. You can edit it afterwards to customize the rules. ### Via the API Set `status` to `DRAFT` if you want to save the policy without enforcing it yet. ```bash theme={null} curl -X POST https://api.truthlocks.com/v1/policies \ -H "X-API-Key: tl_live_..." \ -H "Content-Type: application/json" \ -d '{ "name": "US Issuers Only", "category": "MINT", "status": "ACTIVE", "description": "Restrict minting to US-based issuers", "language": "json_rules", "rules": { "rules": [ { "id": "us_only", "description": "US jurisdiction required", "conditions": [ { "field": "jurisdiction", "op": "eq", "value": "US" } ], "effect": "ALLOW" } ], "default_effect": "DENY" } }' ``` ```json Response theme={null} { "id": "pol_abc123", "name": "US Issuers Only", "category": "MINT", "status": "ACTIVE", "description": "Restrict minting to US-based issuers", "rules": { "..." }, "version": 1, "created_at": "2026-03-31T10:00:00Z" } ``` ## Listing policies ```bash theme={null} curl https://api.truthlocks.com/v1/policies \ -H "X-API-Key: tl_live_..." ``` Returns an array of all policies for the current tenant. ## Simulating a policy Before relying on a policy in production, use the simulator to test how it evaluates a given input. In the console, open the **Simulator** tab on the policies page, select a policy, and enter a test input. You can also call the evaluate endpoint directly: ```bash theme={null} curl -X POST https://api.truthlocks.com/v1/policies/evaluate \ -H "X-API-Key: tl_live_..." \ -H "Content-Type: application/json" \ -d '{ "action": "MINT", "target_type": "ISSUER", "input": { "jurisdiction": "US", "trust_tier": "ENTERPRISE" } }' ``` ```json Response theme={null} { "allowed": true, "matched_rules": ["us_only"], "reasons": [], "decision_id": "dec_7f3a1b" } ``` The response includes four fields: | Field | Type | Description | | - | - | - | | `allowed` | boolean | Whether the request passed all active policies | | `matched_rules` | string\[] | IDs of rules that matched the input. Empty when no rule matched and the default effect applied. | | `reasons` | string\[] | Human-readable explanation when a request is denied. Always an empty array when `allowed` is `true`. | | `decision_id` | string | Unique identifier for this evaluation — use it to look up the full decision record in the [audit trail](/security/audit#policy-decision-audit-trail). | > [!NOTE] > > If you previously relied on `evaluation_ms` in the evaluate response for performance monitoring, that field has been removed from the API response. It is still recorded in the [decision audit trail](#decision-audit-trail) — query `resource_type=policy_decision` in the [audit log](/security/audit#policy-decision-audit-trail) to retrieve it. If no rule matches, the response reflects the `default_effect`: ```json theme={null} { "allowed": false, "matched_rules": [], "reasons": ["Default policy effect: DENY"], "decision_id": "dec_9c2d4e" } ``` ## Decision audit trail Every policy evaluation is recorded automatically. Each decision captures the policy version, matched rules, and a SHA-256 hash of the input for tamper-evidence. Use decision records to trace why a specific request was allowed or denied. The evaluate response includes a `decision_id` you can reference in audit queries: ```bash theme={null} curl "https://api.truthlocks.com/v1/audit/events?resource_type=policy_decision&resource_id=dec_7f3a1b" \ -H "X-API-Key: tl_live_..." ``` The audit record includes fields that are not part of the evaluate API response, such as `evaluation_ms` and `input_hash`: | Decision field | Description | | - | - | | `decision_id` | Unique identifier for this evaluation | | `policy_id` | The policy that was evaluated | | `policy_version` | Version of the policy at evaluation time | | `allowed` | Whether the request was allowed | | `matched_rules` | Rule IDs that matched the input | | `evaluation_ms` | Time spent evaluating, in milliseconds (audit trail only) | | `input_hash` | SHA-256 hash of the evaluation input | ## Deleting a policy Remove a policy from the console by clicking the delete icon on the policy card, or via the API: ```bash theme={null} curl -X DELETE https://api.truthlocks.com/v1/policies/{id} \ -H "X-API-Key: tl_live_..." ``` > [!WARNING] > > Deleting a policy takes effect immediately. Any pending mint or verify requests that were subject to the policy will no longer be evaluated against it. ## Example: multi-rule policy Combine multiple rules to express complex requirements. Rules are evaluated in order — the first match wins. ```json theme={null} { "rules": [ { "id": "block_individual", "description": "Block individual-tier issuers", "conditions": [ { "field": "trust_tier", "op": "eq", "value": "individual" } ], "effect": "DENY" }, { "id": "allow_us_eu", "description": "Allow US or EU jurisdictions", "conditions": [ { "field": "jurisdiction", "op": "in", "value": ["US", "EU"] } ], "effect": "ALLOW" } ], "default_effect": "DENY" } ``` This policy denies individual-tier issuers regardless of jurisdiction, allows US and EU issuers at any other trust tier, and denies everyone else. ## Related > **[Policy engine SDK](/policy)** > > Evaluate policies programmatically using the SDK for custom integration > scenarios. > **[Policy API reference](/api-reference/policies/create)** > > Create, list, evaluate, and delete policies via the REST API. > **[Compliance exports](/guides/compliance-exports)** > > Export audit data in SOC 2, GDPR, and HIPAA formats for compliance > reporting. > **[Governance](/api-reference/governance/list-requests)** > > Use governance workflows for issuer approval and status changes. # Issuer application review Source: https://docs.truthlocks.com/guides/issuer-applications Apply for a higher trust tier and track your application through the review process. New issuers are activated immediately when you [create them](/api-reference/issuers/create), so you can start minting attestations right away at the **Basic** trust level. If your organization needs a higher trust tier — such as **Verified Organization**, **Government Entity**, or **Accredited Institution** — you submit an issuer application for platform review. The review process verifies your organization's identity and assigns a trust tier that determines how your credentials appear to verifiers. ## Prerequisites * A Truthlocks tenant account. [Sign up](https://console.truthlocks.com/auth/sign-up) if you do not have one yet. * Your organization's legal name and registration details. ## Application workflow Every issuer application moves through a defined set of statuses: | Status | Meaning | | :- | :- | | **Draft** | Application created but not yet submitted. You can still edit all fields and upload evidence. | | **Submitted** | Application sent for platform review. No further edits are allowed. | | **In Review** | A platform reviewer is actively evaluating your application. | | **Approved** | Your organization has been granted a higher trust tier. Your issuer's verification badge and trust level are upgraded automatically. | | **Rejected** | The application was declined. The reviewer's reason is shown on the application detail page. | | **Suspended** | A previously approved issuer has been temporarily suspended by the platform. | ## Submitting an application **1. Open issuer applications** In the console, navigate to **Issuers > Apply**. This page lists all your existing applications with their current status. **2. Create a new application** Click **New Application** and fill in the organization details: * **Legal Name** (required) — the full registered legal name of your organization. * **Display Name** — the name shown on credentials and proof pages. If left blank, the legal name is used. * **Jurisdiction** — the country or region where your organization is registered (for example, "United States" or "United Kingdom"). * **Registration Reference** — your company registration or incorporation number. * **Requested Trust Tier** — the level of trust verification you are applying for. **3. Save draft** Click **Save Draft** to create the application. You are redirected to the application detail page where you can upload supporting evidence. **4. Upload evidence** Attach documents that support your application. Accepted evidence types: | Type | Description | | :- | :- | | **Business Registration** | Certificate of incorporation or business registration document | | **Government License** | Relevant government-issued license or permit | | **Proof of Address** | Utility bill, bank statement, or official letter showing your registered address | | **Website Screenshot** | Screenshot of your organization's public website | | **Other Document** | Any additional supporting document | Click the evidence type card to select a file. Files are uploaded securely and attached to your application. **5. Submit for review** When you are satisfied with your application and evidence, click **Submit for Review**. A confirmation dialog warns that you cannot edit the application after submission. > [!WARNING] > > Once submitted, you cannot modify your application or upload additional > evidence unless the reviewer requests changes. ## Trust tiers When submitting, you select a requested trust tier. The platform reviewer may assign a different tier based on the evidence provided. | Tier | Description | | :- | :- | | **Verified Organization** | Standard verification for businesses and organizations. Requires basic identity documentation. | | **Government Entity** | For government agencies and public sector organizations. Requires government-issued documentation. | | **Accredited Institution** | For institutions with industry accreditation (universities, financial institutions, healthcare providers). Requires accreditation certificates. | ## Tracking your application After submission, you can monitor progress from the application detail page: * **Status badge** — the current status is displayed at the top of the page. * **Decision reason** — if your application is rejected or a reviewer leaves feedback, the reason appears in a highlighted banner. * **Activity timeline** — every status change and reviewer action is logged with timestamps and notes, so you can see exactly what happened and when. ## What happens after approval When your application is approved: 1. Your existing issuer is upgraded to the assigned trust tier. 2. Your verification badge on the [Trust Explorer](https://transparency.truthlocks.com) updates automatically based on your [transparency settings](/guides/transparency-settings). 3. Verifiers see the higher trust tier when they check attestations you have issued. > [!NOTE] > > You do not need to wait for approval to start issuing. New issuers are activated at the **Basic** trust level as soon as you [create them](/api-reference/issuers/create). The application process is only required to upgrade to a higher tier. ## Related > **[Console onboarding](/guides/console-onboarding)** > > Complete the guided setup wizard for your tenant. > **[Transparency settings](/guides/transparency-settings)** > > Configure your public directory profile. > **[Signing keys](/api-reference/issuers/keys)** > > Generate and manage issuer signing keys. > **[RBAC](/security/rbac)** > > Manage roles and permissions for your team. # Machine Identity (MAIP) Source: https://docs.truthlocks.com/guides/machine-identity Register, authorize, and monitor AI agents with cryptographic identity and behavioral constraints. # Machine Identity & Agent Identity Protocol The **Machine Agent Identity Protocol (MAIP)** provides identity records for AI agents, bots, and automated services — for registering agents and recording their permissions and activity. > [!WARNING] > > Some MAIP operations currently record caller-supplied results rather than independently executing or verifying them. Document extraction and AI verdicts are simulated; guardrails classify a submitted score; orchestration and workflow handlers create tracking records. Several generated receipts use system markers instead of cryptographic signatures. Read the operation's implementation limitations before relying on its output as evidence. ## Why Machine Identity? As AI agents proliferate across enterprise workflows, organizations face a critical challenge: **How do you know which agent did what, and whether it was authorized?** MAIP solves this with: * **Cryptographic agent identity** — Every agent gets a unique ID (`maip-agent:`) and signing keys * **Scope-based authorization** — Fine-grained permission scopes control what each agent can do * **Runtime policy enforcement** — [MAIP policies](/guides/maip-policies) evaluate trust scores, scopes, and delegation depth before every sensitive action * **Trust scoring** — Continuous behavioral evaluation produces a 0-100 trust score * **Session management** — Time-bounded execution contexts with automatic expiry * **Cross-tenant delegation** — Agents can delegate authority across organizational boundaries * **Kill switch** — Instant emergency revocation of any agent's access ## Architecture ``` ┌─────────────────────────────────────────────┐ │ Your Application │ │ ┌─────────┐ ┌─────────┐ ┌─────────────┐ │ │ │ Agent A │ │ Agent B │ │ Agent C │ │ │ └────┬────┘ └────┬────┘ └──────┬──────┘ │ │ │ │ │ │ │ ┌────▼────────────▼──────────────▼──────┐ │ │ │ MAIP SDK (JS / Go / Py) │ │ │ └────────────────┬──────────────────────┘ │ └───────────────────┼─────────────────────────┘ │ HTTPS ┌───────────────▼───────────────┐ │ Machine Identity Service │ │ ┌──────┐ ┌───────┐ ┌──────┐ │ │ │Agents│ │Scopes │ │Trust │ │ │ │ │ │ │ │Scores│ │ │ └──────┘ └───────┘ └──────┘ │ └───────────────────────────────┘ ``` ## Try it in the playground Every MAIP endpoint has an interactive API playground built into the docs. You can build requests, switch between [Sandbox and Production](/environments#try-it-in-the-api-playground) environments, and send them directly — no separate tool needed. All MAIP endpoints are covered, spanning ten API groups: [Machine Agents](/api-reference/machine-identity/agents/register), [Agent Sessions & Tools](/api-reference/machine-identity/sessions/create), [Trust & Witness](/api-reference/machine-identity/trust-scores/get), [MAIP Policies](/api-reference/machine-identity/policies/list), [Truth Claims & Documents](/api-reference/machine-identity/truth-claims/create), [Compliance & Anomalies](/api-reference/machine-identity/compliance/create-check), [Datasets & Models](/api-reference/machine-identity/datasets/attest), [Orchestrations & Workflows](/api-reference/machine-identity/orchestrations/execute), [Guardrails & Delegation](/api-reference/machine-identity/guardrails/check), and [Observability](/api-reference/machine-identity/observability/events). The playground supports both `X-API-Key` and Bearer JWT authentication. Use `X-API-Key` for quick testing and Bearer JWT when you need to authenticate with a session token from a running agent. > [!TIP] > > Open any endpoint in the [Machine Agents](/api-reference/machine-identity/agents/register) API reference and click **Send** to try it live against the Sandbox. ## Quick start ### 1. Register an agent ```bash cURL theme={null} curl -X POST https://api.truthlocks.com/v1/agents \ -H "X-API-Key: $API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "order-processor", "type": "autonomous", "scopes": ["receipts:write", "attestations:read"], "metadata": { "framework": "langchain", "model": "gpt-4o", "owner": "platform-team" } }' ``` ```javascript JavaScript theme={null} import { TruthlocksMAIP } from "@truthlocks/sdk"; const maip = new TruthlocksMAIP({ apiKey: process.env.TL_API_KEY }); const agent = await maip.agents.register({ name: "order-processor", type: "autonomous", scopes: ["receipts:write", "attestations:read"], metadata: { framework: "langchain", model: "gpt-4o", owner: "platform-team", }, }); ``` ### 2. Create a Session ```bash theme={null} curl -X POST https://api.truthlocks.com/v1/agent-sessions \ -H "X-API-Key: $API_KEY" \ -d '{ "agent_id": "maip-agent:01JXXXX", "scopes": ["receipts:write"], "ttl_seconds": 3600, "ip_allowlist": ["10.0.0.0/8"] }' ``` ### 3. Execute with Trust Scoring Every action the agent takes is logged and scored. The trust score updates continuously: ```bash theme={null} # Check current trust score curl https://api.truthlocks.com/v1/trust-scores/maip-agent:01JXXXX \ -H "X-API-Key: $API_KEY" ``` Response: ```json theme={null} { "agent_id": "maip-agent:01JXXXX", "score": 87, "factors": { "behavioral_compliance": 92, "scope_adherence": 95, "anomaly_score": 12, "peer_attestations": 78 }, "trend": "stable", "computed_at": "2026-04-06T12:00:00Z" } ``` ### 4. Emergency Kill Switch Instantly revoke all agent access: ```bash theme={null} curl -X POST https://api.truthlocks.com/v1/agents/maip-agent:01JXXXX/kill \ -H "X-API-Key: $API_KEY" \ -d '{ "reason": "Anomalous behavior detected", "revoke_sessions": true }' ``` ## Core Concepts ### Agent Types | Type | Description | Use Case | | - | - | - | | `autonomous` | Fully autonomous decision-making | Trading bots, workflow engines | | `supervised` | Requires human approval for critical actions | Content moderation, compliance | | `delegated` | Acts on behalf of another agent or user | Service accounts, proxies | | `system` | Infrastructure-level agent | Monitoring, health checks | ### Scopes Scopes follow a `resource:action` pattern: * `agents:read` / `agents:write` — Agent management * `receipts:write` — Issue action receipts * `attestations:read` — Read attestation data * `trust-scores:read` — Access trust scores * `delegations:offer` / `delegations:accept` — Cross-tenant delegation * `compliance:write` — Run compliance checks * `orchestrations:execute` — Execute multi-agent workflows ### Trust Score Components | Factor | Weight | Description | | - | - | - | | Behavioral compliance | 35% | Actions within declared scope | | Scope adherence | 25% | No out-of-scope access attempts | | Anomaly score | 20% | Deviation from historical patterns | | Peer attestations | 10% | Other agents vouching for behavior | | Session hygiene | 10% | Proper session creation/termination | ## Billing & Quotas Machine identity features are metered per your plan. Four MAIP usage counters are tracked each billing cycle: | Metric | What it counts | Developer | Business | Enterprise | | :- | :- | :- | :- | :- | | `maip.agents` | Registered machine agents | 2 | 50 | Plan-dependent | | `maip.sessions` | Agent sessions created per month | 100 | 10,000 | Plan-dependent | | `maip.trust_computes` | On-demand trust score calculations | 50 | 5,000 | Plan-dependent | | `maip.compliance_checks` | Compliance verification requests | 10 | 500 | Plan-dependent | Monitor your consumption with the [usage API](/api-reference/billing/usage) or in the console at **Settings > Billing > Usage** under the **MAIP** section. > [!NOTE] > > See the [billing overview](/billing/overview#metered-products) for the full list of 16 metered products. Upgrade your plan at [console.truthlocks.com/billing](https://console.truthlocks.com/billing) to increase limits. ## Editor and pipeline integrations MAIP integrates with the tools your team already uses. Each integration generates cryptographic receipts automatically. | Category | Integrations | | :- | :- | | **Editor plugins** | [VS Code](/guides/maip-integrations#vs-code-extension), [JetBrains](/guides/maip-integrations#jetbrains-plugin), [Neovim](/guides/maip-integrations#neovim-plugin) (Telescope, statusline, auto-receipt on save) | | **AI assistants** | [MCP Server](/guides/maip-integrations#mcp-server) — 20 tools for AI coding assistants to query agents, receipts, and trust scores | | **Data pipelines** | [Event-stream library and Kafka connector](/guides/maip-integrations#event-streaming) — provider adapters require concrete clients; standalone gateway is not ready | | **CI/CD** | [GitHub Action](/guides/maip-integrations#github-action) — receipts for commits, PRs, releases, and build artifacts | | **AI frameworks** | LangChain, LlamaIndex, CrewAI, AutoGen, OpenAI, Anthropic, AWS Bedrock | | **Team tools** | Slack, Linear, Notion | See the [MAIP integrations guide](/guides/maip-integrations) for setup instructions and code examples. ## Next steps > **[Agent authorization](/guides/agent-authorization)** > > Deep dive into scope-based authorization and session management. > **[MAIP policies](/guides/maip-policies)** > > Runtime enforcement rules based on trust scores, scopes, and delegation depth. > **[Trust scores](/guides/trust-scores)** > > Understanding and configuring continuous trust evaluation. > **[Cross-tenant delegation](/guides/cross-tenant-delegation)** > > Enable agents to operate across organizational boundaries. > **[AI orchestration](/guides/ai-orchestration)** > > Multi-agent workflow execution with safety guardrails. > **[MAIP integrations](/guides/maip-integrations)** > > Connect agents to Slack, GitHub, VS Code, Neovim, LangChain, and more. # MAIP integrations Source: https://docs.truthlocks.com/guides/maip-integrations Connect your AI agents to the tools and platforms your team already uses. # MAIP integrations The Machine Agent Identity Protocol (MAIP) ships with integrations that bring agent identity, receipts, and trust scoring into your existing workflows. Local evidence, hosted receipt submission and signature verification are separate operations. Configure and test the integration you use; installation alone does not create a complete audit trail. > [!NOTE] > > **Prerequisites:** You need a Truthlocks account with an API key and at least one registered agent. See the [machine identity guide](/guides/machine-identity) to register your first agent. > [!TIP] > > Browse the available integrations on the [Integrations Hub](https://truthlocks.com/resources/integrations). Links are grouped by SDK, AI framework, editor and collaboration tool. ## Developer tools ### VS Code extension A sidebar panel for browsing receipts, generating receipts from your editor, and viewing trust data. Install it from the [Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=truthlocks.maip-vscode). **What it does:** * Browse and search MAIP receipts from the sidebar * Generate receipts for code changes directly from the editor * View agent trust scores and receipt chains **Installation:** 1. Open VS Code and go to the Extensions view (`Ctrl+Shift+X` / `Cmd+Shift+X`). 2. Search for "Truthlocks MAIP". 3. Click **Install**. Alternatively, install from the command line: ```bash theme={null} code --install-extension truthlocks.maip-vscode ``` After installing, open the MAIP sidebar panel and enter your API key and agent ID to connect. ### JetBrains plugin MAIP integration for IntelliJ, PyCharm, and WebStorm with the same receipt browsing and generation capabilities as the VS Code extension. ### Neovim plugin Install the released `truthlocks/maip.nvim` plugin, with curl available on your PATH: ```lua theme={null} -- lazy.nvim { "truthlocks/maip.nvim", tag = "v1.1.0", main = "maip", opts = { api_url = "https://sandbox-api.truthlocks.com/v1", api_key = vim.env.MAIP_API_KEY or "", agent_id = vim.env.MAIP_AGENT_ID or "", auto_receipt_on_commit = false, telescope = false, } } ``` Use `:MAIPListAgents`, `:MAIPCreateReceipt`, `:MAIPListReceipts`, `:MAIPVerifyReceipt`, `:MAIPShowTrust` and `:MAIPDashboard`. Receipt metadata is not a verified signature. Automatic commit receipts are opt-in and observe supported completed commit events; there is no `auto_receipt` on-save option in this release. See the [versioned README](https://github.com/truthlocks/maip.nvim) for Telescope configuration and the current interactive-test limits. ### MCP server Install the executable on the machine running your MCP host: ```sh theme={null} npm install --global @truthlocks/maip-mcp-server@1.2.4 ``` ```json theme={null} { "mcpServers": { "truthlocks": { "command": "maip-mcp-server", "env": { "MAIP_API_URL": "https://sandbox-api.truthlocks.com/v1", "MAIP_API_KEY": "REPLACE_WITH_WORKSPACE_TEST_KEY", "MAIP_TIMEOUT_MS": "30000", "MAIP_MAX_RETRIES": "3" } } } } ``` Supply credentials through the host's secure configuration. Use a key and agent from the same environment. Ask the host to list available tools, then use `maip_list_agents`, `maip_list_receipts` and `maip_verify_receipt`. A positive signature result requires `valid: true`, `signature_verified: true` and `verdict: "VALID"`. Transparency verification is a separate result. Writes are not automatically retried. ## Team collaboration Slack, Linear and Notion integrations require their own real application/workspace credentials in addition to Truthlocks authentication. Their complete provider-to-receipt acceptance is still outstanding. Do not treat source availability, local tests or a Truthlocks API key as proof that an external workspace is connected. Review the source package README for provider permissions and configuration: [Slack](https://github.com/truthlocks/truthlock/tree/main/packages/maip-slack), [Linear](https://github.com/truthlocks/truthlock/tree/main/packages/maip-linear), [Notion](https://github.com/truthlocks/truthlock/tree/main/packages/maip-notion). Use a dedicated test workspace before enabling real event processing. ### Slack setup and validation Slack is a source installation, not a published `@truthlocks/maip-slack` npm package. Its bot authentication and an authorized test-message submission passed provider checks. Full personal-user slash-command and hosted event workflows remain under validation. Follow the [Slack README](https://github.com/truthlocks/truthlock/tree/main/packages/maip-slack) for the reviewed build and all required settings. Bind the app to `SLACK_TEAM_ID` and explicit personal `SLACK_ALLOWED_USER_IDS`. Use `MAIP_AGENT_ID` from an existing registered Truthlocks agent for creation; a Slack Member ID is not a machine identity. Supply a sandbox key and `https://sandbox-api.truthlocks.com/v1` during evaluation. Commands are registered in Slack's app settings. Both HTTP and Socket Mode provide `/webhook/maip`, but hosting the listener does not automatically subscribe Truthlocks events to it. Delegation approvals remain in authenticated Console review. Local replay protection is process-local; production delivery needs durable upstream tracking. ### Notion setup and validation Notion is a private source package, not an npm installation. Real QA acceptance created a child page and database schemas, inserted an existing workspace receipt, repeated the sync without duplicating that page, and checked provider readback. Continuous hosted automation and durable recovery remain under validation. Connect only the intended page using Notion's **••• → Connections** menu. Follow the [Notion README](https://github.com/truthlocks/truthlock/tree/main/packages/maip-notion) to initialize databases once and reuse their IDs. Use `WEBHOOK_SECRET` with the versioned HMAC/timestamp contract; unsigned requests are rejected. Receipt status is metadata, so a completed receipt does not automatically check the Notion **Verified** box. Use explicit signature verification separately. ## CI/CD The MAIP action's inputs are `maip-api-url`, `maip-api-key` and `maip-agent-id`. The older `api-key` and `agent-id` names are not declared inputs. For a reviewed source checkout with its built `dist/index.js`, an explicitly triggered QA workflow can use this step: ```yaml theme={null} - uses: ./packages/maip-github-action with: maip-api-url: https://sandbox-api.truthlocks.com/v1 maip-api-key: ${{ secrets.TRUTHLOCKS_API_KEY }} maip-agent-id: ${{ vars.TRUTHLOCKS_AGENT_ID }} mode: receipt event-type: commit create-check: 'false' post-comment: 'false' ``` This is a local action path after checkout and build, not an unverified Marketplace tag. Pin reviewed releases when distributing the action. Check/comment publishing requires deliberate GitHub permissions and separate acceptance; never expose secrets to workflows from untrusted forks. See the [action README](https://github.com/truthlocks/truthlock/tree/main/packages/maip-github-action). ## AI model connectors Python wrappers capture events emitted through the configured integration. Local hashes are not server signatures. Provider credentials, Truthlocks credentials and hosted submission are configured separately; inspect the metadata you send and do not assume hashing removes privacy obligations. ### Supported frameworks | Framework | Install | | :- | :- | | LangChain | `pip install truthlocks-langchain` | | LlamaIndex | `pip install truthlocks-llamaindex` | | CrewAI | `pip install truthlocks-crewai` | | AutoGen | `pip install truthlocks-autogen` | | OpenAI | `pip install truthlocks-openai` | | Anthropic | `pip install truthlocks-anthropic` | | AWS Bedrock | `pip install truthlocks-bedrock` | **Complete local LangChain example (no hosted request):** ```python theme={null} from langchain_core.runnables import RunnableLambda from truthlocks_langchain import MAIPRunnableWrapper from maip_ai_connectors.config import MAIPConfig chain = RunnableLambda(lambda value: value.upper()) wrapped = MAIPRunnableWrapper(chain, config=MAIPConfig(auto_receipt=False)) print(wrapped.invoke("hello")) receipts = wrapped.get_receipts() print(receipts[0].payload_hash) wrapped.clear_receipts() ``` `payload_hash` describes local evidence. For hosted submission use `MAIPClient.create_receipt` and verify the returned server `receipt_id`; the [LangChain README](https://github.com/truthlocks/truthlock/tree/main/packages/truthlocks-langchain) contains the async submission example. For asynchronous automatic hooks, flush and close the wrapper and inspect submission results before shutdown. Calls outside the configured wrapper are not observed. ## Data and ML pipelines ### Kafka connector The Go connector submits message fingerprints as MAIP `data.attestation` receipts using an existing agent. Its HTTP client uses `/v1/agent-receipts`, preserves partial batch outcomes, and requires a confirmed signature for successful verification. Install `github.com/truthlocks/kafka-maip-connector@v0.1.0` with `go get`. See the [release and complete example](https://github.com/truthlocks/kafka-maip-connector/releases/tag/v0.1.0). The API key selects the workspace and environment; a caller-supplied tenant ID does not override authorization. Message bytes and raw message keys are not uploaded. The producer/consumer wrappers buffer receipts in memory. Broker delivery and receipt delivery are separate operations; a successful Kafka write does not guarantee a receipt was retained. Required audit delivery needs a durable application outbox and explicit failure handling. Consult the release evidence before production use. ### Event streaming Install [Go event-stream v0.1.0](https://github.com/truthlocks/maip-event-stream/releases/tag/v0.1.0): ```sh theme={null} go get github.com/truthlocks/maip-event-stream@v0.1.0 ``` The library includes a concrete Redis client and adapter interfaces for NATS JetStream, EventBridge and Kinesis. Redis reconnecting consumers scan their own pending entries before new messages; failed processing remains unacknowledged. Keep consumer names stable across restarts. Claiming another consumer's pending entries still requires an explicit recovery process. The published artifact passed an isolated real Redis restart/acknowledgement test and the complete Go race suite. Other backend adapters require real, authenticated client implementations. These adapters transport event envelopes; they do not automatically mint or verify MAIP signatures. Kafka receipt generation is a separate connector, described above. > [!WARNING] > > The standalone gateway is not ready for deployment: its backend client factories > are not wired, and it now refuses startup rather than reporting unperformed > publications as accepted. There is no released `truthlocks_streaming.StreamingGateway` > Python API corresponding to the older example on this page. Deduplication now uses a bounded exact cache of confirmed event identities, scoped to tenant and source. Failed publications are not cached. Retries default to zero; explicit retries provide at-least-once delivery, not exactly-once guarantees. The batch middleware handles one event at a time so it cannot guess failed items from aggregate counts. Cache eviction and process restart can permit duplicates. The receipt validator checks structure and local hash links; it is not a signature verifier. Keep authenticated routing, durable retention and cryptographic validation in your application design. ### MLflow, DVC and Delta Lake Install `mlflow-maip`, `dvc-maip` or `delta-lake-maip` for the corresponding metadata builders. These packages produce local structured evidence; installing one does not make every framework operation a signed hosted receipt. There is no supported `truthlocks_mlflow.TruthlocksPlugin.enable` API corresponding to the older example. Use the complete local and hosted examples in the source READMEs: [MLflow](https://github.com/truthlocks/truthlock/tree/main/packages/mlflow-maip), [DVC](https://github.com/truthlocks/truthlock/tree/main/packages/dvc-maip), [Delta Lake](https://github.com/truthlocks/truthlock/tree/main/packages/delta-lake-maip). Provider metadata and artifact URIs do not independently verify artifact bytes or prove that an external operation occurred. Hosted signature verification does not establish transparency-log inclusion unless that separate check succeeds. ## Docker Container source files do not establish that a public image has been released or passed acceptance. The previously listed `truthlocks/*:latest` images and combined Compose example have not been verified as a working deployment and are not a supported quickstart. Do not infer image availability from those historical names. Use the published package release and its README for each integration. If building a container from reviewed source, pin that revision and dependencies, supply secrets through your runtime, and test the actual provider connection. Slack additionally requires its real application credentials; a Truthlocks API key alone is insufficient. The standalone event-stream gateway remains unavailable as described above. ## Next steps > **[Machine identity](/guides/machine-identity)** > > Register your first agent and understand the MAIP protocol. > **[Agent authorization](/guides/agent-authorization)** > > Configure scopes, sessions, and tool access for your agents. > **[Downloads](https://truthlocks.com/resources/downloads)** > > Find published CLI, SDK and IDE releases and their installation instructions. > **[Integrations hub](https://truthlocks.com/resources/integrations)** > > Browse all integrations by category. ### Linear Real provider authentication, SDK issue lookup and a receipt comment with readback passed in an explicitly authorized QA issue. This does not establish hosted webhook receipt creation or continuous synchronization. The source listener verifies Linear's HMAC signature and signed timestamp, and restricts events to configured organization and team IDs. Project milestone automation remains unavailable rather than emitting estimated evidence. See the [Linear setup and limits](https://github.com/truthlocks/truthlock/tree/main/packages/maip-linear#readme). # MAIP policies Source: https://docs.truthlocks.com/guides/maip-policies Define runtime enforcement rules that control what AI agents can do based on trust scores, scopes, delegation depth, and agent type. MAIP policies let you enforce guardrails on AI agent behavior at runtime. When an agent requests access to a scoped resource, all active policies are evaluated before the action proceeds. If any policy denies the request, the action is blocked. > [!NOTE] > > MAIP policies are different from [issuance policies](/guides/issuance-policies). Issuance policies govern **credential minting and verification** for human users and issuers. MAIP policies govern **machine agent behavior** at runtime — controlling what agents can do based on trust scores, delegation depth, scopes, and agent type. ## When to use MAIP policies Use MAIP policies when you need to: * Block agents with low trust scores from performing sensitive operations * Require human approval when an agent is deep in a delegation chain * Restrict specific agent types (e.g., `llm` or `worker`) from accessing certain scopes * Enforce different rules for different risk levels without changing agent code * Add runtime guardrails to multi-agent orchestration workflows If you don't create any MAIP policies, agent access is controlled only by scope assignments and agent status. ## How policies work Each MAIP policy contains one or more **rules**. Each rule has: * **Conditions** — field-level checks evaluated against the requesting agent's context * **Effect** — `allow`, `deny`, or `require_approval` * **requires\_approval** — optional flag that triggers a human approval workflow Rules within a policy are evaluated independently. If **any** rule with a `deny` effect matches, the action is blocked regardless of any `allow` rules. This is a **deny-overrides** model. ``` Agent requests scope → Evaluate all active policies (priority order) │ ┌────────┼────────┐ ▼ ▼ ▼ Policy A Policy B Policy C (p: 10) (p: 20) (p: 100) │ │ │ ▼ ▼ ▼ Any deny? ──yes──→ Action BLOCKED │ no │ ▼ Action ALLOWED ``` ### Evaluation order 1. **Agent status** — the agent must be `active`. Suspended or revoked agents are always denied. 2. **Scope check** — the requested scope must be in the agent's granted scopes. Explicitly denied scopes (prefixed with `!`) always block access. 3. **Policy rules** — all active tenant policies are evaluated in priority order (lower numbers first). Each rule's conditions are AND-ed. ### Condition fields | Field | Type | Operators | Description | | - | - | - | - | | `trust_score` | number | `lt`, `gt`, `le`, `ge` | Agent's current trust score (0.0–1.0) | | `scope` | string | `eq`, `ne`, `in`, `contains` | The scope being requested (e.g., `data:write`) | | `agent_type` | string | `eq`, `ne`, `in` | Agent type (e.g., `llm`, `worker`, `orchestrator`) | | `delegation_depth` | number | `gt`, `ge`, `lt`, `le` | Position in the delegation chain (0 = direct) | ### Operators | Operator | Description | Example value | | - | - | - | | `eq` | Equals | `"data:write"` | | `ne` | Not equals | `"system"` | | `lt` | Less than | `0.5` | | `gt` | Greater than | `3` | | `le` | Less than or equal | `0.3` | | `ge` | Greater than or equal | `0.7` | | `in` | Matches any value in a list | `["llm", "worker"]` | | `contains` | String contains substring | `"write"` | ### Effects | Effect | Behavior | | - | - | | `allow` | Explicitly allow the action. Does not override denials from other rules. | | `deny` | Block the action. First deny wins. | | `require_approval` | Allow the action but flag it for human approval before proceeding. | ## Creating a policy ```bash cURL theme={null} curl -X POST https://api.truthlocks.com/v1/maip/policies \ -H "X-API-Key: $API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Block Low-Trust Write Operations", "description": "Deny data:write scope for agents with trust score below 0.5", "category": "trust", "priority": 10, "rules": [ { "conditions": [ {"field": "trust_score", "op": "lt", "value": 0.5}, {"field": "scope", "op": "eq", "value": "data:write"} ], "effect": "deny", "requires_approval": false } ] }' ``` ```javascript JavaScript theme={null} const response = await fetch("https://api.truthlocks.com/v1/maip/policies", { method: "POST", headers: { "X-API-Key": "tl_live_...", "Content-Type": "application/json", }, body: JSON.stringify({ name: "Block Low-Trust Write Operations", description: "Deny data:write scope for agents with trust score below 0.5", category: "trust", priority: 10, rules: [ { conditions: [ { field: "trust_score", op: "lt", value: 0.5 }, { field: "scope", op: "eq", value: "data:write" }, ], effect: "deny", requires_approval: false, }, ], }), }); const policy = await response.json(); ``` ```python Python theme={null} import requests response = requests.post( "https://api.truthlocks.com/v1/maip/policies", headers={ "X-API-Key": "tl_live_...", "Content-Type": "application/json", }, json={ "name": "Block Low-Trust Write Operations", "description": "Deny data:write scope for agents with trust score below 0.5", "category": "trust", "priority": 10, "rules": [ { "conditions": [ {"field": "trust_score", "op": "lt", "value": 0.5}, {"field": "scope", "op": "eq", "value": "data:write"}, ], "effect": "deny", "requires_approval": False, } ], }, ) policy = response.json() ``` All new policies are created with `status: "active"` and take effect immediately. ### Policy categories | Category | Use case | | - | - | | `scope` | Restrict access based on specific scopes or resources | | `trust` | Restrict access based on trust score thresholds | | `rate` | Restrict access frequency or volume | | `custom` | Custom enforcement logic (default if omitted) | ### Priority The `priority` field controls evaluation order. Lower numbers are evaluated first. Range: 1–1000. Default: `100`. If multiple policies share the same priority, they are evaluated in creation order. ## Evaluating policies at runtime Call the evaluate endpoint before your agent performs a sensitive operation. The response tells you whether the action is allowed, denied, or requires human approval. ```bash theme={null} curl -X POST https://api.truthlocks.com/v1/maip/policies/evaluate \ -H "X-API-Key: $API_KEY" \ -H "Content-Type: application/json" \ -d '{ "agent_id": "maip:t1234567:01HYX3KPZQ7RJGBN0WFMV8SDEH", "scope": "data:write", "action": "update_customer_record", "resource": "customers/cust_12345" }' ``` **Allowed response:** ```json theme={null} { "allowed": true, "requires_approval": false } ``` **Denied response:** ```json theme={null} { "allowed": false, "denied_by": ["Block Low-Trust Write Operations"], "reason": "denied by policy", "requires_approval": false } ``` **Requires approval response:** ```json theme={null} { "allowed": true, "requires_approval": true } ``` When `requires_approval` is `true`, your application should route the action through a human approval workflow before proceeding. ## Listing policies ```bash theme={null} curl https://api.truthlocks.com/v1/maip/policies \ -H "X-API-Key: $API_KEY" ``` Returns all MAIP policies for your tenant, including their rules, priority, and status. ## Common patterns ### Block untrusted agents from writing data Deny any agent with a trust score below 0.5 from accessing write scopes. ```json theme={null} { "name": "Block Low-Trust Writes", "category": "trust", "priority": 10, "rules": [ { "conditions": [ { "field": "trust_score", "op": "lt", "value": 0.5 }, { "field": "scope", "op": "eq", "value": "data:write" } ], "effect": "deny" } ] } ``` ### Require approval for deep delegation chains Agents more than three levels deep in a delegation chain must get human approval for any action. ```json theme={null} { "name": "Approval for Deep Delegation", "category": "scope", "priority": 20, "rules": [ { "conditions": [ { "field": "delegation_depth", "op": "gt", "value": 3 } ], "effect": "require_approval", "requires_approval": true } ] } ``` ### Restrict LLM agents from executing tools Prevent LLM-type agents from invoking tool execution scopes while allowing other agent types. ```json theme={null} { "name": "No Tool Execution for LLMs", "category": "scope", "priority": 15, "rules": [ { "conditions": [ { "field": "agent_type", "op": "eq", "value": "llm" }, { "field": "scope", "op": "eq", "value": "tool:execute" } ], "effect": "deny" } ] } ``` ### Block multiple agent types from a scope Use the `in` operator to match against a list of values instead of writing separate rules for each agent type. ```json theme={null} { "name": "No Autonomous Writes", "category": "scope", "priority": 10, "rules": [ { "conditions": [ { "field": "agent_type", "op": "in", "value": ["llm", "worker"] }, { "field": "scope", "op": "eq", "value": "data:write" } ], "effect": "deny" } ] } ``` ### Deny all write scopes with a single rule Use the `contains` operator to match any scope that includes a substring, rather than listing each write scope individually. ```json theme={null} { "name": "Read-Only for Low Trust", "category": "trust", "priority": 10, "rules": [ { "conditions": [ { "field": "trust_score", "op": "lt", "value": 0.5 }, { "field": "scope", "op": "contains", "value": "write" } ], "effect": "deny" } ] } ``` ### Combine multiple rules in one policy A single policy can contain multiple rules for layered enforcement: ```json theme={null} { "name": "Production Safety Net", "category": "custom", "priority": 5, "rules": [ { "conditions": [ { "field": "trust_score", "op": "lt", "value": 0.3 } ], "effect": "deny" }, { "conditions": [ { "field": "trust_score", "op": "lt", "value": 0.7 }, { "field": "scope", "op": "eq", "value": "data:write" } ], "effect": "require_approval", "requires_approval": true } ] } ``` This policy blocks agents with trust scores below 0.3 outright, and requires human approval for write operations from agents scoring between 0.3 and 0.7. ## MAIP policies vs. RBAC policies | | MAIP policies | RBAC (issuance) policies | | - | - | - | | **Governs** | Machine agent runtime behavior | Credential minting, verification, and export | | **Subjects** | AI agents identified by MAIP ID | Human users and issuers | | **Condition fields** | `trust_score`, `scope`, `agent_type`, `delegation_depth` | `jurisdiction`, `trust_tier`, `risk_rating`, `key.age_days` | | **Evaluation model** | Deny-overrides (any deny blocks) | First-match wins | | **API path** | `/v1/maip/policies` | `/v1/policies` | ## Related > **[MAIP Policies API reference](/api-reference/machine-identity/policies/list)** > > Create, list, and evaluate MAIP policies via the REST API. > **[Trust scores](/guides/trust-scores)** > > Understand the trust scoring system that feeds into policy conditions. > **[Agent authorization](/guides/agent-authorization)** > > Scope-based authorization and session management for agents. > **[Machine identity](/guides/machine-identity)** > > Full overview of the Machine Agent Identity Protocol. # Observability dashboard Source: https://docs.truthlocks.com/guides/observability Monitor attestation volume, service health across 10 backend services, latency percentiles, and plan usage from the console. The observability dashboard gives you a real-time view of your Truthlocks environment directly in the console. Use it to track attestation activity, monitor service health, spot latency trends, and check plan usage — all without leaving the browser. The dashboard is available in two views: a **platform observability** dashboard for platform administrators, and a **tenant observability** dashboard for tenant users. > [!NOTE] > > The tenant observability dashboard is available on **Business** and **Enterprise** plans. If you are on a Free or Starter plan, you will see an upgrade prompt when you navigate to the dashboard. The platform observability dashboard is available to all platform administrators. See [billing](/billing/overview) for plan details. ## Platform observability Navigate to **Observability** in the platform console sidebar. The dashboard presents SLO performance, service health, error distribution, and cloud infrastructure links in a single page with interactive charts. ### KPI row Four cards with colored left-border accents display top-level metrics: | Card | Accent color | What it shows | | :- | :- | :- | | **Gateway** | Cyan | Current gateway status (e.g. "operational") | | **Services** | Green | Healthy services out of total (e.g. "9/10") | | **SLO Status** | Purple | Overall SLO status badge — green, amber, or red | | **Recent Errors** | Red | Count of recent grouped errors | ### SLO performance When SLO data is available, the dashboard displays three visualizations: #### Availability gauge A radial bar gauge showing the current availability percentage. The gauge is color-coded: | Color | Availability | | :- | :- | | Green | 99.9% or higher | | Amber | 99.0% – 99.9% | | Red | Below 99.0% | The error budget consumed is displayed below the gauge. #### SLO scorecards Two scorecards show: * **Availability** — the current percentage against the 99.9% target. * **p99 Latency** — the worst-case response time against the 200 ms target. Each scorecard is color-coded — green when within target, amber when approaching the threshold, and red when the target is breached. #### SLO trend charts Two seven-day line charts show the historical trend for availability and p99 latency. A dashed amber reference line marks the SLO target on each chart. Use these to spot whether your SLOs are trending toward or away from target. ### Service health The services section includes three views: * **Service health donut** — a compact radial chart showing the ratio of healthy, degraded, and unknown services. * **Service latency chart** — a horizontal bar chart showing each service's response time in milliseconds. Bars are color-coded by latency (green under 50 ms, cyan under 200 ms, amber under 500 ms, red above). A dashed reference line at 200 ms marks the SLA threshold. * **Service detail cards** — expandable cards for each backend service showing status, target URL, response time with a proportional progress bar, and links to logs and traces. The platform dashboard monitors the following services: | Service | Description | | :- | :- | | API Gateway | Main API endpoint for all inbound requests | | Trust Registry | Identity, issuers, keys, and governance | | Attestation Service | Credential minting and lifecycle | | Signing Service | Cryptographic key management and signing | | Transparency Log | Tamper-evident append-only Merkle tree | | Verification Service | Credential verification and validation | | Audit Service | Tamper-proof audit trail with hash chaining | | Billing Service | Usage metering and subscription management | | Machine Identity | Agent registration, sessions, and trust scoring | | AI CMO | AI content moderation and orchestration | Each service displays its current status (**healthy**, **degraded**, or **down**). A service is marked **degraded** when it responds but takes longer than 2 seconds, and **down** when it fails to respond within the 5-second timeout. ### Error distribution A bar chart breaks down recent grouped errors by signature, color-coded for quick identification. Below the chart, each error group shows its count, source, and sample trace IDs. Links to CloudWatch Logs Insights and X-Ray Service Map are provided when available. ### CloudWatch launchers Quick-launch buttons for your cloud monitoring tools — Dashboard, Metrics, Logs Insights, X-Ray, and Alarms. These open directly in your AWS console. ### Trace lookup Enter a trace ID to get a direct link to AWS X-Ray (or your OTLP backend) for that specific request. Press Enter or click **Look up** to resolve the trace. ### Auto-refresh The dashboard polls all data sources every 30 seconds. Toggle auto-refresh on or off from the header. A countdown shows when the next refresh will occur. Click **Refresh** at any time to fetch the latest data immediately. ## Tenant observability Navigate to **Observability** in the tenant console sidebar. The tenant dashboard is organized into four tabs with interactive charts. ### Dashboard tabs | Tab | What it shows | | :- | :- | | **Overview** | Top-level stats, performance gauges, attestation lifecycle charts, and a latency trend chart | | **Services** | Per-service health, SLA compliance bars, uptime percentages, latency details, and a multi-service latency trend | | **Usage & Quotas** | Consumption of mints, verifications, storage, and other metered resources with a horizontal bar chart | | **Security** | Cryptographic integrity, tenant isolation, and audit trail posture cards with detailed control tables | ### Overview The overview tab displays four primary stat cards: * **Total attestations** — active, revoked, and superseded counts. * **Active issuers** — how many of your issuers are currently trusted. * **Audit events** — total events recorded with hash-chain integrity. * **System health** — how many backend services are healthy out of the total monitored. Below the stat cards, three performance gauges show: * **Average latency** across all services. * **P95 latency** — the worst-case response time for the slowest service. * **Health checks performed** since the page was opened. #### Attestation lifecycle chart A donut chart breaks down your total attestations into **active** (green), **revoked** (red), and **other** (gray) categories. A companion bar chart shows the same data with counts and percentages for each category. #### Latency trend chart An area chart overlays response times for all monitored services over recent health checks. Each service is color-coded with its own gradient fill. A legend below the chart identifies each service. The SLA thresholds are noted: green under 200 ms, yellow under 500 ms, red at 1000 ms or above. ### Services The services tab shows the health of each monitored backend service: | Service | Description | | :- | :- | | API Gateway | Main API endpoint for all inbound requests | | Trust Registry | Identity, issuers, keys, and governance | | Attestation Service | Credential minting and lifecycle | | Signing Service | Cryptographic key management and signing | | Transparency Log | Tamper-evident append-only Merkle tree | | Verification Service | Credential verification and validation | | Audit Service | Tamper-proof audit trail with hash chaining | | Billing Service | Usage metering and subscription management | | Machine Identity | Agent registration, sessions, and trust scoring | | AI CMO | AI content moderation and orchestration | Each service displays its current status (**healthy**, **degraded**, or **down**), response time, and session uptime percentage. An SLA compliance bar compares each service's uptime against the 99.9% target. > [!NOTE] > > Uptime percentages shown on the services tab are session-scoped — they reset each time you open the dashboard. For historical uptime data, visit the [public status page](https://status.truthlocks.com) or query the [status API](/ops/health#programmatic-status-api). ### Usage and quotas The usage tab displays a horizontal bar chart showing each metered resource's consumption as a percentage of its plan limit. Bars are color-coded: | Color | Usage level | | :- | :- | | Cyan | Normal (under 80%) | | Amber | High (80% or above) | | Red | At limit (100%) | Meters without a configured quota are listed separately below the chart. Hover over any bar to see the exact count and limit. > [!TIP] > > If a usage meter is approaching its limit, consider upgrading your plan or contacting support for a custom quota. Once a limit is reached, API requests for that operation return HTTP 402. See [rate limits](/ops/limits) for details. ### Security The security tab gives you a live view of your environment's security posture across three dimensions. At the top, three posture cards summarize overall strength: | Posture card | What it measures | | :- | :- | | **Cryptographic integrity** | Ed25519 signatures, SHA-256 audit hashing, and Merkle tree transparency. | | **Tenant isolation** | PostgreSQL row-level security, per-tenant keys, and gateway-level enforcement. | | **Audit trail** | Hash-chained event count with integrity verification status. Shows "Attention" until your first audit event is recorded. | Below the posture cards, individual security controls are grouped into three categories: #### Cryptographic controls | Control | Algorithm | Description | | :- | :- | :- | | Attestation signing | Ed25519 (EdDSA) | Every attestation is cryptographically signed with an Ed25519 key. | | Audit hash chain | SHA-256 | Audit events are chained with SHA-256 hashes so tampering is detectable. | | Auth / JWKS | ES256 (ECDSA P-256) | JWT tokens and JWKS keys use ES256 for authentication. | | Transparency log | Merkle tree / SHA-256 | A tamper-evident Merkle tree provides public auditability. | #### Access controls | Control | Mechanism | Description | | :- | :- | :- | | Row-level security | PostgreSQL RLS | All database tables enforce tenant isolation at the row level. | | RBAC | Role-based access control | Granular permissions scoped to your defined roles. | | API gateway | nginx + rate limiting | Per-IP and per-tenant rate limits enforced at the gateway. | | Service auth | Internal service keys | Service-to-service communication is authenticated with shared keys. | #### Data protection controls | Control | Mechanism | Description | | :- | :- | :- | | Tenant isolation | Multi-tenant RLS | Complete data segregation between tenants at the database level. | | Audit immutability | Append-only + hash chain | Events cannot be deleted or modified after creation. Shows "Attention" until your first event is recorded. | | Key rotation | Per-issuer key lifecycle | Keys can be rotated and superseded without losing historical attestations. | Each control shows an **Enforced** badge when active or an **Attention** badge when it requires action (for example, if no audit events have been recorded yet). ## Tenant dashboard charts The main tenant dashboard (**Home** page in the console sidebar) includes three attestation insight charts when you have at least one attestation: | Chart | Type | What it shows | | :- | :- | :- | | **Attestation status** | Donut (pie) | Breakdown of active, revoked, and other attestations with a color-coded legend | | **Issuer coverage** | Bar chart | Active issuers versus total issuers configured | | **Platform health** | Radial gauge | Percentage of attestations that are currently active, displayed as a half-circle gauge | These charts provide a quick visual summary of your attestation portfolio health without navigating to the full observability dashboard. ## Programmatic monitoring For machine-readable health data outside the console, use the [status API](/ops/health#programmatic-status-api) or the [billing usage endpoint](/api-reference/billing/usage). These endpoints let you integrate Truthlocks metrics into your own dashboards or alerting pipelines. ## Next steps > **[Health and readiness](/ops/health)** > > Health endpoints, status page, and monitoring integrations. > **[Billing usage](/api-reference/billing/usage)** > > Track mints, verifications, and storage via the API. > **[Rate limits](/ops/limits)** > > Plan quotas and how to handle 429 and 402 responses. > **[Audit logs](/security/audit)** > > Query and export your audit trail. # Onboarding checklist Source: https://docs.truthlocks.com/guides/onboarding Step-by-step guide to setting up your Truthlocks tenant and going live. When you create a new Truthlocks tenant, an onboarding checklist guides you through every step needed to start issuing attestations. The checklist tracks your progress and picks up where you left off each time you sign in. ## Onboarding steps The checklist contains seven steps. All steps except "Invite team members" are required before you can go live. **1. Complete tenant profile** Set your company name, industry, and contact information. This metadata appears on your invoices, compliance reports, and in the admin directory. **2. Create an organization** Define your organizational structure. The organization is the top-level entity that owns issuers, keys, and team members. **3. Invite team members (optional)** Add collaborators to your workspace. You can skip this step and invite people later from **Settings > Team**. **4. Set up an issuer profile** Configure your credential-issuing identity — the name, logo, and metadata that appear on attestations and proof pages. **5. Generate signing keys** Create an Ed25519 signing key pair for your issuer. These keys are used to cryptographically sign every attestation you mint. **6. Mint a test attestation** Verify your pipeline end-to-end by minting a test attestation in the sandbox environment. This confirms that your issuer, keys, and configuration are working correctly. **7. Activate your tenant** Review your setup and go live. Once activated, your tenant can mint production attestations and your issuer appears in the public transparency log. ## Progress tracking A banner on your console dashboard shows how many steps you have completed and links directly to your next step. The banner disappears automatically once you activate your tenant. You can also navigate to any completed or current step from the onboarding page at any time — the wizard remembers your progress. > [!NOTE] > > If you close the progress banner, you can return to the checklist from > **Settings > Onboarding** or by visiting `/onboarding` in your console URL. ## Environments During onboarding, all operations run in the **sandbox** environment. After activation, your tenant gains access to the production environment. See [environments](/environments) for details on switching between sandbox and production. ## What happens after activation Once you activate your tenant: * Your issuer profile is published to the [transparency log](https://transparency.truthlocks.com). * You can mint production attestations via the console or [API](/api-reference/attestations/mint). * Billing begins based on your selected [plan tier](/billing/overview). * Your team members receive full access according to their [assigned roles](/security/rbac). ## Related > **[Quickstart](/quickstart)** > > End-to-end guide to minting your first attestation. > **[Environments](/environments)** > > Sandbox vs. production and how to switch between them. > **[RBAC](/security/rbac)** > > Assign roles and permissions to your team. > **[Billing](/billing/overview)** > > Plan tiers, usage metering, and add-ons. # Public collection Source: https://docs.truthlocks.com/guides/portfolio Choose a public handle and share only the records you select for public visibility. A public collection lists records you have selected for public sharing. Visitors can open each record and run a current check. A listing does not independently establish authorship, ownership, or the truth of a claim. ## Choose a collection address 1. Sign in to your personal workspace and open **Profile → Public collection**. 2. Enter a handle using 3–30 letters, numbers, hyphens, or underscores. Handles are case-sensitive. 3. Review which records have public visibility and confirm the effect. 4. Select **Save collection address**. If the handle is already used, choose another. Your collection address is `https://verify.truthlocks.com/portfolio/your-handle`. It displays the public handle and up to 100 public records, with the total available count. It does not publish your sign-in email or private profile display name. An active personal account is required. Business workspaces and suspended accounts do not have a public personal collection through this endpoint. ## Change or disable the address You can change your handle on the same page. Links to the previous address will stop locating your collection, and the previous handle can become available to another account. To disable the collection address, leave the handle empty and confirm. This does **not** make individual public records private or invalidate existing record links. Open **Your collection → a record → Change visibility** to adjust a record's descriptive visibility. ## API example Use a consumer-session bearer token. A business API key does not authorize changes to a personal collection handle. ```bash theme={null} curl -X PUT https://api.truthlocks.com/v1/consumer/me/username \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{"username":"my-collection"}' ``` A successful response reports `status: updated` and the saved `username`. Send `{"username":""}` to disable the address. A conflict returns HTTP 409; invalid characters return HTTP 400. Public readers can call `GET /v1/consumer/portfolio/{username}` without credentials. The response contains the public handle, public record projections, and a total count. HTTP 404 means no matching active personal collection was found. Other failures should be treated as unavailability, not evidence that a record is invalid. # Privacy center Source: https://docs.truthlocks.com/guides/privacy-center Export your data, request account deletion, and manage your privacy rights. The Truthlocks Privacy Center gives you control over your personal data. You can request a full data export, delete your account, and track the status of privacy requests. Access it from your dashboard at `verify.truthlocks.com/privacy`. ## Data export Request a copy of all data associated with your account. Exports are delivered in JSON format and include your profile information, protections, credentials, and activity history. **1. Request an export** Open the Privacy Center and click **Request Data Export**. The request enters a processing queue. **2. Wait for processing** Export requests are processed within a few minutes. You can track the status on the Privacy Center page. **3. Download your data** Once the status changes to **Completed**, a download link appears in the **Available Downloads** section. Click it to download your JSON export. > [!NOTE] > > Export files contain personal data. Store them securely and delete them when > you no longer need them. ### Export via the API You can also request exports programmatically: ```bash theme={null} curl -X POST https://api.truthlocks.com/v1/consumer/privacy/export \ -H "X-API-Key: tlk_your_key_here" \ -H "Content-Type: application/json" \ -d '{"format": "json"}' ``` ```json Response theme={null} { "job_id": "prv_export_abc123", "status": "PENDING", "created_at": "2026-03-25T12:00:00Z" } ``` Poll the job status or check the **Available Downloads** section once processing completes. ## Account deletion Deleting your account permanently removes all your data, protections, credentials, and signing keys. This action cannot be undone. **1. Request deletion** In the Privacy Center, click **Request Account Deletion**. **2. Confirm with your email** A confirmation dialog asks you to type your account email address to proceed. This prevents accidental deletions. **3. Processing** Deletion requests are processed within 30 days, in compliance with data protection regulations. You can continue using your account until processing begins. > [!WARNING] > > Account deletion is irreversible. All attestations, protections, and > credentials linked to your account will be permanently erased. Existing > proof pages and badges will stop resolving. ## Tracking privacy requests The Privacy Center displays a list of your recent privacy requests with real-time status updates: | Status | Meaning | | - | - | | **Pending** | Request received, waiting to be processed | | **Approved** | Request approved and queued for execution | | **Processing** | Actively being processed | | **Completed** | Request fulfilled (download available for exports) | | **Failed** | An error occurred; contact support | | **Expired** | Download link expired; request a new export | ## Data retention policies Tenant administrators can set per-category retention rules from **Settings > Privacy** in the console. Retention policies control how long data is kept before automatic deletion. ### Supported data classes | Data class | Description | | :- | :- | | **Audit logs** | Console and API activity logs | | **Consumer inbox** | Credentials delivered to consumers | | **Verification events** | Records of third-party verifications | | **Webhook deliveries** | Outbound webhook delivery logs | ### Default retention values Every new tenant starts with the following per-category defaults: | Data class | Default retention | Default delete mode | | :- | :- | :- | | **Audit logs** | 365 days | Soft only | | **Consumer inbox** | 90 days | Soft then hard | | **Verification events** | 365 days | Soft only | | **Webhook deliveries** | 30 days | Soft then hard | You can adjust these at any time from the console. In addition to per-category rules, the platform enforces an overall attestation data retention period of **2 years (730 days)** by default. This covers attestations, audit logs, evidence, and verification records at the platform level. The 2-year period applies unless you have the extended retention add-on enabled. > [!NOTE] > > Enterprise plans include an extended retention add-on that increases the > platform-level retention ceiling to **10 years (3,650 days)**. When enabled, > the extended period applies to attestations, audit logs, evidence, and > verification records. Contact sales to enable it. ### How retention is enforced A background job runs daily to process expired records. Records past their retention period are handled in batches to minimize system load. The job applies your configured delete mode: * **Soft only** — records are marked as archived but the data is preserved. * **Soft then hard** — records are permanently deleted after the retention period. ### Configuring a policy Each data class has three settings: * **Retention days** — how long to keep records (0–3,650 days). Set to 0 to retain indefinitely. * **Delete mode** — `Soft only` marks records as deleted but retains the data, or `Soft then hard` permanently purges records after the soft-delete period. * **Enabled** — toggle to activate or deactivate the policy. Changes take effect immediately when saved. A background job runs daily to process expired records in batches. ### Legal holds When you need to preserve data for legal or compliance reasons, create a legal hold to pause automatic deletion for a specific scope. **1. Open privacy settings** Navigate to **Settings > Privacy** in the console and scroll to the **Legal Holds** section. **2. Create a hold** Click **Create Hold** and provide: * **Scope type** — Tenant, Organization, User, or Resource * **Scope ID** — the identifier for the entity (UUID) * **Reason** — why the hold is needed (minimum 10 characters) **3. Release when no longer needed** Click **Release** on an active hold and confirm in the dialog. Data covered by the hold resumes normal retention processing. > [!WARNING] > > Releasing a legal hold is permanent. Once released, data covered by the hold > becomes subject to your retention policies and may be deleted automatically. > [!NOTE] > > Account deletion requests are blocked while a legal hold covers the user's > data. The hold must be released before the deletion can proceed. ## Your privacy rights Truthlocks supports the following data rights in compliance with GDPR and similar regulations: > **Right to access** > > Request a full copy of your personal data at any time through the data > export feature. > **Right to erasure** > > Request permanent deletion of your account and all associated data. > **Right to portability** > > Export your data in a structured, machine-readable JSON format. > **Processing transparency** > > Track the status of all privacy requests in real time from the Privacy > Center. ## For developers > **[Request data export](/api-reference/consumer/privacy/export)** > > `POST /v1/consumer/privacy/export` > **[Request account deletion](/api-reference/consumer/privacy/delete-account)** > > `POST /v1/consumer/privacy/delete-account` > **[List privacy jobs](/api-reference/consumer/privacy/jobs)** > > `GET /v1/consumer/privacy/jobs` ## Next steps > **[Account security](/guides/account-security)** > > Set up MFA and manage active sessions. > **[Content protection](/guides/content-protection)** > > Learn how to protect your content with cryptographic attestations. # Protect GitHub Action Source: https://docs.truthlocks.com/guides/protect-action Record private file fingerprints from GitHub workflows and verify original artifact bytes. The Protect action hashes selected files locally and creates signed fingerprint records using a consumer account. File contents are not uploaded. The signature binds a fingerprint to a record; it does not establish authorship, copyright ownership, or whether a description is true. ## Before you start Use an authorized consumer bearer token from your Truthlocks Verify account. A business API key is not interchangeable with that token. Store the token in a GitHub repository secret named `TRUTHLOCK_TOKEN`. Do not expose it to untrusted pull requests or print it in logs. The action installs the pinned `@truthlocks/protect@1.1.1` CLI with Node.js 22. Start with a manually triggered workflow and a labeled test artifact. ## Quickstart ```yaml theme={null} # .github/workflows/protect.yml name: Protect an artifact on: workflow_dispatch: permissions: contents: read jobs: protect: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: truthlocks/truthlock/packages/protect-action@e9609a43a494f785984cac708cc123db17ff0310 id: protect with: token: ${{ secrets.TRUTHLOCK_TOKEN }} files: '["artifacts/report.pdf"]' category: research visibility: private title-prefix: 'Release artifact - ' - name: Report created record count env: RECORD_COUNT: ${{ steps.protect.outputs.protection-count }} run: echo "Created $RECORD_COUNT record(s)" ``` Replace `artifacts/report.pdf` with an existing file in your checked-out repository. For release workflows, build the artifact before running this action. Pin a reviewed full commit SHA for production workflows. ## Inputs | Input | Required | Default | Meaning | | - | - | - | - | | `token` | Yes | — | Authorized consumer bearer token. | | `files` | One of files/directory | — | Space-separated patterns, or a JSON array for paths containing spaces. | | `directory` | One of files/directory | — | Recursively select files inside the workspace. | | `category` | No | `code` | Content classification. | | `visibility` | No | `private` | `private` or explicitly `public`. | | `algorithm` | No | `managed` | Consumer signing is managed; other values are rejected. | | `title-prefix` | No | Empty | Text prepended to each file's title. | Supported categories are `code`, `research`, `design`, `media`, `dataset`, `ai-output`, `writing`, `digital-art`, and `other`. Directory selection excludes `.git`, `node_modules`, and symlinks. Inputs must stay inside the workspace. Unmatched patterns and an empty selection fail. ## Outputs and verification | Output | Meaning | | - | - | | `attestation-ids` | Comma-separated IDs for the created records. | | `protection-count` | Number of files successfully processed. | | `badge-url` | Public-record badge URL; empty for private records. | Minting a record does not itself verify its signature. With the same original file, use the CLI to verify a current consumer record: ```sh theme={null} npx --yes --package @truthlocks/protect@1.1.1 truthlock-protect verify YOUR_ATTESTATION_UUID --personal-record --file ./artifacts/report.pdf --json ``` Replace the ID and file path. The CLI reconstructs the defined personal-record-v2 signed payload from the file hash. It exits successfully only when the verifier returns `VALID` with `signature_verified: true`. Changed bytes fail verification. An ID-only request is `INCOMPLETE`; it cannot establish a valid signature. Private records are excluded from the public consumer portfolio and do not have public certificate/badge pages. Do not publish their IDs or assume the visibility flag hides all verification metadata from someone who already knows an ID. ## Partial failures and retries Each file creates a separate remote record. The action stops at the first failed CLI call; earlier records can already exist. Inspect those outcomes before rerunning a batch, since a repeat may create additional records. There is no all-or-nothing batch transaction or automatic mutation retry. ## Related * [Protect CLI: saved receipts and workspace verification](/guides/protect-cli) * [Content protection](/guides/content-protection) # Protect CLI Source: https://docs.truthlocks.com/guides/protect-cli Record file fingerprints from a consumer account or business workspace, then verify the original file. Record a file's SHA-256 fingerprint and verify it later with Truthlocks. Files are hashed locally: the CLI sends the fingerprint and record metadata, not the file contents. **Runtime:** Node.js 18+ · **Package:** `@truthlocks/protect` · **Command:** `truthlock-protect` [Console](https://console.truthlocks.com) · [Consumer app](https://verify.truthlocks.com) · [API documentation](https://docs.truthlocks.com) ## Install ```sh theme={null} npm install --global @truthlocks/protect truthlock-protect --help ``` The `truthlocks` command is also installed as an alias. This package records online fingerprints; use `@truthlocks/cli` for offline proof-bundle verification. ## Choose your account type | Account | Credential | Signing setup | | - | - | - | | Business workspace | `TRUTHLOCKS_API_KEY` | An active issuer and a key available for signing in the console. | | Consumer account | `TRUTHLOCK_TOKEN` | An authorized consumer bearer token; Truthlocks manages its signing key. | An API key is not a consumer token. The CLI uses different endpoints for these two workflows. Test API keys select the sandbox host. Set `TRUTHLOCK_API_URL` only when you intentionally need a different API origin. ## Workspace quickstart Set `TRUTHLOCKS_API_KEY`, `TRUTHLOCKS_ISSUER_ID` and `TRUTHLOCKS_KEY_ID` in your environment, then protect an existing file: ```sh theme={null} truthlock-protect whoami truthlock-protect protect ./report.pdf --title "Quarterly report" --idempotency-key report-release-2026-10-11 --output ./report.receipt.json --json ``` Replace the example retry key with a unique value for this operation. Retain it with the request details and reuse it only for the identical request. The output contains `attestation_id` and `payload_b64url`; retain both. The `--output` option saves a receipt without overwriting an existing file. This operation writes a record. You can select the issuer and key explicitly instead: ```sh theme={null} truthlock-protect protect ./report.pdf --issuer-id YOUR_ISSUER_UUID --key-id YOUR_SIGNING_KEY_ID --algorithm Ed25519 --json ``` Replace the uppercase placeholders. The algorithm must match the selected key. If exactly one active issuer and one eligible signing key are available, the CLI can select them automatically; otherwise it asks you to choose using flags. Workspace records use structured claims with a `document.sha256` fingerprint and an explicit document hash. They follow workspace/API access rules; consumer visibility flags do not apply to this workflow. ## Consumer quickstart Set `TRUTHLOCK_TOKEN` to an authorized consumer bearer token, with workspace API-key environment variables unset, then run: ```sh theme={null} truthlock-protect whoami truthlock-protect protect ./design.png --title "Design source" --private --output ./design.receipt.json --json ``` Consumer records are private by default. Use `--public` only when you want a public consumer record. The service selects the consumer signing key; `--algorithm`, `--issuer-id` and `--key-id` are workspace options and are rejected in consumer mode. ## Verify a record and file Use the saved receipt and the original file. The receipt supplies the exact bytes that were signed; the file supplies the fingerprint to compare: ```sh theme={null} truthlock-protect verify --receipt ./report.receipt.json --file ./report.pdf --json ``` For a current consumer record, you can reconstruct its defined personal-record-v2 payload from the original file: ```sh theme={null} truthlock-protect verify YOUR_ATTESTATION_UUID --personal-record --file ./design.png --json ``` This reconstruction is automatic when using only a consumer token with `--file`. It does not reconstruct arbitrary workspace claims or historical payload formats. For a workspace record without a saved receipt, supply the original signed payload bytes using `--payload-file ./signed-payload.json`. Do not reformat that JSON. Exit code 0 requires both `verdict: VALID` and `signature_verified: true`. Altered files and incomplete proofs exit nonzero. An ID-only lookup cannot verify a signature; it reports `INCOMPLETE` unless a stronger status such as revocation applies: ```sh theme={null} truthlock-protect verify YOUR_ATTESTATION_UUID --json ``` A valid fingerprint record is evidence that bytes match the recorded hash. It does not independently prove authorship, copyright ownership, or the truth of its title. ## Commands | Command | Purpose | | - | - | | `protect ` / `p ` | Record one regular file's fingerprint. | | `verify [id] --receipt --file ` | Verify the retained signed payload and compare original file bytes. | | `list [--limit 20] [--json]` | Read records available to the configured account. | | `whoami` | Check workspace access or consumer account information. | | `login --token ` | Save a consumer token locally. Environment variables avoid saving it. | | `logout` | Remove the saved consumer token; environment variables and workspace credentials remain. | | `register --email ` | Register a developer workspace and save its sandbox API key. | Developer registration is a separate account-creation operation. It does not create a consumer session or guarantee an issuer/signing key is already provisioned. ## Options and local storage `protect` accepts `--title`, `--description`, `--category`, `--content-type`, `--json`, `--api-key`, `--issuer-id`, `--key-id`, `--algorithm`, `--idempotency-key` and `--output`. `--public` and `--private` apply only to consumers. File category is auto-detected unless supplied. Directories are not supported. The historical `TRUTHLOCK_API_KEY` variable is still accepted. Explicit API-key flags and environment variables take priority over a saved developer key. An explicit consumer-token environment variable takes priority over a saved developer key when no API-key environment variable is supplied. A saved consumer token lives in `~/.truthlock/config.json`; developer credentials live in `~/.truthlocks/credentials.json`. These are local credential files. Keep them out of repositories and backups intended for publication. ## Troubleshooting | Message or result | Next step | | - | - | | No credentials | Configure the credential for the intended account type. | | Choose an issuer or key | Supply the IDs shown in the console; confirm the key can sign. | | Environment mismatch | Match test/production keys to the correct API host. | | Consumer signing keys are managed | Remove workspace-only flags or use a workspace API key. | | `INCOMPLETE` | Supply the saved receipt or exact signed payload; an ID or file hash alone is insufficient for workspace signatures. | | `ALTERED` | Verify that you supplied the exact original file. | | Request timed out | Check the operation's outcome before retrying; retain the original retry key. | Requests use a 30-second timeout and are sent once. Redirects are rejected. Rate-limit remaining values are not presented as a monthly quota. ## Upgrading from 1.0 Version 1.1.1 adds retained signed payloads and cryptographic verification with original files. Version 1.1 fixes API-key headers, consumer `content_hash`, workspace signing, private consumer defaults, JSON output, command aliases and real verification. Previous examples that claimed a protection lookup was cryptographic verification should be replaced. MIT license. # Receipts Source: https://docs.truthlocks.com/guides/receipts Cryptographically signed, transparency-log-anchored receipts for any event ## What Are Receipts? Receipts are signed, immutable records of discrete events — payments, security incidents, compliance checks, deliveries, and more. Unlike logs or audit trails, every receipt is: * **Cryptographically signed** with your issuer key (Ed25519 or ES256) * **Anchored in the transparency log** with a Merkle inclusion proof * **Offline-verifiable** via proof bundle export * **Idempotent** — the same event always produces the same receipt ## Receipt types Platform-defined receipt types are available to all tenants. Each type has a JSON Schema that the `payload` field is validated against before signing. | Type | Use Case | | - | - | | `payment_receipt` | Payments, invoices, refunds | | `security_event_receipt` | Auth events, key rotations, anomalies | | `delivery_receipt` | Document delivery, notifications | | `compliance_receipt` | KYC/AML checks, regulatory evidence | | `custom_receipt` | Any other event with open schema | ### Discovering available types Call [`GET /v1/receipt-types`](/api-reference/receipts/list-types) to list every type your tenant can use, or [`GET /v1/receipt-types/{name}`](/api-reference/receipts/get-type) to fetch a single type and inspect its JSON Schema. ```typescript JavaScript theme={null} const types = await client.receipts.listTypes(); // Inspect a specific type's schema const paymentType = await client.receipts.getType("payment_receipt"); console.log(paymentType.schema.required); // ["amount", "currency", "provider", ...] ``` ```go Go theme={null} types, _ := client.Receipts.ListTypes(ctx) for _, t := range types.Items { fmt.Println(t.Name, t.Version) } // Pin a specific version rt, _ := client.Receipts.GetType(ctx, "payment_receipt@1.0.0") ``` ## Minting a receipt The example uses illustrative IDs and payload values. Replace them with your workspace issuer, available signing key, and a payload matching the selected receipt-type schema. Do not submit the example as a real payment record. **1. Choose a receipt type** Call `GET /v1/receipt-types` to list available types and inspect the schema for required fields. **2. Build your payload** Construct the `payload` object matching the required fields for your receipt type. For `payment_receipt`, you need `amount`, `currency`, `provider`, `provider_reference`, and `subject`. **3. Mint via API** ```bash theme={null} curl -X POST https://api.truthlocks.com/v1/receipts \ -H "X-API-Key: tl_live_..." \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "issuer_id": "550e8400-e29b-41d4-a716-446655440000", "kid": "ed-key-2026", "alg": "Ed25519", "receipt_type": "payment_receipt", "subject": "customer@example.com", "payload": { "amount": 5000, "currency": "USD", "provider": "stripe", "provider_reference": "ch_3Px..." } }' ``` **4. Store the receipt\_id** The response includes the `receipt_id` and `log.leaf_index`. Store both for future verification. ## SDK Examples ```typescript JavaScript theme={null} const receipt = await client.receipts.mint({ issuer_id: 'your-issuer-id', kid: 'ed-key-2026', alg: 'Ed25519', receipt_type: 'payment_receipt', subject: 'customer@example.com', payload: { amount: 5000, currency: 'USD', provider: 'stripe', provider_reference: 'ch_3Px...' } }); console.log(receipt.receipt_id, receipt.log.leaf_index); ``` ```go Go theme={null} receipt, err := client.Receipts.Mint(ctx, &truthlock.MintReceiptRequest{ IssuerID: "your-issuer-id", KID: "ed-key-2026", Alg: "Ed25519", ReceiptType: "payment_receipt", Subject: "customer@example.com", Payload: map[string]interface{}{ "amount": 5000, "currency": "USD", "provider": "stripe", "provider_reference": "ch_3Px...", }, }) ``` ### Listing receipts ```typescript JavaScript theme={null} const receipts = await client.receipts.list({ receipt_type: "payment_receipt", status: "active", limit: 20, }); ``` ```go Go theme={null} receipts, err := client.Receipts.List(ctx, &truthlock.ListReceiptsFilter{ ReceiptType: "payment_receipt", Status: "active", Limit: 20, }) ``` ### Retrieving a receipt ```typescript JavaScript theme={null} const receipt = await client.receipts.get("receipt-uuid"); ``` ```go Go theme={null} receipt, err := client.Receipts.Get(ctx, "receipt-uuid") ``` ## Webhook events Subscribe to receipt events by configuring a webhook endpoint in the console: | Event | Triggered When | | - | - | | `receipt.created` | A receipt is successfully minted | | `receipt.revoked` | A receipt is revoked | ## Revoking a receipt Revocation is permanent and recorded in the transparency log. Receipts with status `revoked` remain queryable and their revocation timestamp is included in proof bundles. You can include an optional `reason` to record why the receipt was revoked. ```bash theme={null} curl -X POST https://api.truthlocks.com/v1/receipts/{id}/revoke \ -H "X-API-Key: tl_live_..." \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{"reason": "Duplicate charge refunded"}' ``` ```typescript JavaScript theme={null} await client.receipts.revoke("receipt-uuid", { reason: "Duplicate charge refunded", }); ``` ```go Go theme={null} _, err := client.Receipts.Revoke(ctx, "receipt-uuid", &truthlock.RevokeReceiptRequest{ Reason: "Duplicate charge refunded", }) ``` ## Verifying a receipt Use the verify endpoint to check a receipt's cryptographic validity and current status. The API checks the signature, key status, and revocation state, then returns a verdict. ```bash theme={null} curl -X POST https://api.truthlocks.com/v1/receipts/verify \ -H "X-API-Key: tl_live_..." \ -H "Content-Type: application/json" \ -d '{ "receipt_id": "receipt-uuid" }' ``` ```typescript JavaScript theme={null} const result = await client.receipts.verify("receipt-uuid"); if (result.verdict === "VALID") { console.log("Receipt is valid"); } ``` ```go Go theme={null} result, err := client.Receipts.Verify(ctx, "receipt-uuid") if result.Verdict == "VALID" { fmt.Println("Receipt is valid") } ``` ```python Python theme={null} result = client.receipts.verify("receipt-uuid") if result["verdict"] == "VALID": print("Receipt is valid") ``` ### Verdicts | Verdict | Meaning | | - | - | | `VALID` | Signature is valid, key is active, receipt is not revoked | | `REVOKED` | Receipt has been explicitly revoked | | `INVALID_SIGNATURE` | Cryptographic signature verification failed | | `KEY_COMPROMISED` | Signing key was marked compromised at or before issuance | | `KEY_INACTIVE` | Signing key is no longer active | | `NOT_FOUND` | Receipt not found for this tenant | ## Proof bundles A proof bundle is a self-contained package for offline verification. It includes the signed receipt envelope, Merkle inclusion proof from the transparency log, and the issuer key snapshot at issuance time. After downloading a proof bundle, you can verify the receipt without making any further API calls. ```typescript JavaScript theme={null} const bundle = await client.receipts.getProofBundle("receipt-uuid"); console.log(bundle.bundle_version); // "receipt-v1" console.log(bundle.transparency_log); // Merkle inclusion proof ``` ```go Go theme={null} bundle, err := client.Receipts.GetProofBundle(ctx, "receipt-uuid") ``` ```python Python theme={null} bundle = client.receipts.get_proof_bundle("receipt-uuid") ``` See the [proof bundle API reference](/api-reference/receipts/proof-bundle) for the full bundle structure. > [!TIP] > > You can download proof bundles directly from the console. Open a receipt's detail page and click **Download Proof Bundle**. See [downloading in the console](#downloading-a-proof-bundle). ## Searching receipts Search across your receipts using full-text search and faceted filters. The search index supports queries against payload content, and you can narrow results by type, status, date range, or indexed payload fields. ```bash theme={null} curl -X POST https://api.truthlocks.com/v1/receipts/search \ -H "X-API-Key: tl_live_..." \ -H "Content-Type: application/json" \ -d '{ "q": "stripe", "receipt_type": "payment_receipt", "from_date": "2026-01-01T00:00:00Z", "limit": 20 }' ``` ```typescript JavaScript theme={null} const results = await client.receipts.search({ q: "stripe", receipt_type: "payment_receipt", from_date: "2026-01-01T00:00:00Z", limit: 20, }); for (const r of results.items) { console.log(r.receipt_id, r.receipt_type); } ``` ```go Go theme={null} results, err := client.Receipts.Search(ctx, &truthlock.SearchReceiptsQuery{ Q: "stripe", ReceiptType: "payment_receipt", FromDate: "2026-01-01T00:00:00Z", Limit: 20, }) ``` ```python Python theme={null} results = client.receipts.search( q="stripe", receipt_type="payment_receipt", from_date="2026-01-01T00:00:00Z", limit=20, ) ``` ### Search filters | Field | Type | Description | | - | - | - | | `q` | string | Full-text search across payload content | | `receipt_type` | string | Filter by type name | | `status` | string | `active`, `revoked`, `superseded`, or `redacted` | | `issuer_id` | UUID | Filter by issuer | | `from_date` | RFC 3339 | Start of date range | | `to_date` | RFC 3339 | End of date range | | `index_key` | string | Indexed payload field name | | `index_value` | string | Value to match for `index_key` | | `limit` | integer | Max results (1–100, default 20) | | `offset` | integer | Pagination offset | > [!TIP] > > You can also search receipts from the console without writing code. Open **Receipts** in the sidebar and use the search bar and filter controls. See [searching in the console](#searching-receipts-1). ## Exporting receipts Queue an asynchronous bulk export of receipts as JSON or CSV. The API returns immediately with a job ID. Poll the export status endpoint until `status` is `complete`, then download from the pre-signed URL. ```typescript JavaScript theme={null} // Start an export const job = await client.receipts.export({ format: "json", filters: { receipt_type: "payment_receipt", status: "active", }, }); console.log(job.id, job.status); // "pending" // Poll for completion const completed = await client.receipts.getExport(job.id); if (completed.status === "complete") { console.log("Download:", completed.download_url); } // List all export jobs const exports = await client.receipts.listExports(); ``` ```go Go theme={null} job, err := client.Receipts.Export(ctx, &truthlock.CreateExportRequest{ Format: "json", Filters: map[string]interface{}{ "receipt_type": "payment_receipt", "status": "active", }, }) // Poll for completion completed, err := client.Receipts.GetExport(ctx, job.ID) ``` ```python Python theme={null} job = client.receipts.export( format="json", filters={"receipt_type": "payment_receipt", "status": "active"}, ) # Poll for completion completed = client.receipts.get_export(job["id"]) if completed["status"] == "complete": print("Download:", completed["download_url"]) ``` ### Export status values | Status | Meaning | | - | - | | `pending` | Queued, not yet started | | `running` | Processing records | | `complete` | Done — `download_url` is available | | `failed` | Error — see `error_message` | > [!TIP] > > You can queue exports and track their progress from the console. Open **Receipts**, click **Export**, and choose CSV or JSON. A status banner tracks the job until the download is ready. See [exporting in the console](#exporting-receipts-1). ## Redacting receipts Redaction permanently removes PII from a receipt's payload while preserving the cryptographic proof. The receipt's signature, transparency log entry, and Merkle inclusion proof remain intact — only the `payload_json` is replaced with a redaction marker. Use this for GDPR right-to-erasure requests on receipts containing personal data. ```typescript JavaScript theme={null} await client.receipts.redact("receipt-uuid"); ``` ```go Go theme={null} _, err := client.Receipts.Redact(ctx, "receipt-uuid") ``` ```python Python theme={null} client.receipts.redact("receipt-uuid") ``` > [!WARNING] > > Redaction is permanent. The original payload cannot be restored. The cryptographic proof remains valid for audit purposes. After redaction: * `status` changes to `redacted` * `payload_json` is replaced with `{"redacted": true, "redacted_by": "tenant_request"}` * A `RECEIPT_REDACT` event is anchored in the transparency log * All other fields (signature, log proof, receipt type) are preserved ## Managing receipts in the console You can manage the full receipts lifecycle from the console without writing any code. Open **Receipts** in the console sidebar to access the following features. ### Searching receipts The receipts list page includes a search bar and filters. Type a keyword to search across receipt payloads, or use the filter controls to narrow results by receipt type, status, issuer, or date range. Results update in real time as you refine your query. ### Exporting receipts Click **Export** from the receipts list to queue a bulk export as CSV or JSON. A status banner appears at the top of the page tracking the job through `pending`, `running`, and `complete` states. Once the export finishes, click the banner to download the file. You can also monitor export jobs from the API using `GET /v1/receipt-exports/{id}` — see [export receipts](/api-reference/receipts/export). ### Downloading a proof bundle Open any receipt's detail page and click **Download Proof Bundle** to save a self-contained verification package. The bundle includes the signed receipt envelope, Merkle inclusion proof, and issuer key snapshot — everything needed for [offline verification](#proof-bundles). ### Redacting a receipt From any active receipt's detail page, click **Redact** to permanently remove personally identifiable information from the payload. A confirmation dialog explains that redaction is irreversible before you proceed. Redaction is only available for receipts with `active` status. After redaction, the cryptographic proof and transparency log entry are preserved — only the payload content is removed. See [redacting receipts](#redacting-receipts) for details on what changes. ## Retention policy Receipts are automatically cleaned up based on the retention policy set at mint time. A background worker sweeps expired receipts on a regular schedule. Set `retention_policy` when minting: | Policy | Duration | Description | | - | - | - | | `standard` | 2 years | Default. Suitable for most transactional receipts. | | `extended` | 7 years | For compliance use cases requiring longer retention. | | `permanent` | Never | Never automatically deleted. | Receipts approaching their retention deadline can be redacted instead of deleted if you need to preserve the cryptographic proof while removing payload data. ## Next steps > **[Proof bundle specification](/specification/proof-bundle)** > > Full structure and offline verification steps for proof bundles. > **[Receipts API reference](/api-reference/receipts/mint)** > > Complete API reference for minting, searching, exporting, and redacting receipts. > **[Webhooks](/guides/webhooks)** > > Subscribe to receipt events and process them in real time. > **[Issuance policies](/guides/issuance-policies)** > > Enforce approval workflows and constraints on receipt minting. # Risk signals Source: https://docs.truthlocks.com/guides/risk-signals Ingest fraud-detection signals from any source, normalize identity events into scored signals, and query them by entity, score, or type. Risk signals let you feed fraud-detection data into Truthlocks from any upstream provider — device fingerprinting services, IP reputation APIs, email verification tools, document analysis engines, or your own internal rules. Once ingested, signals are available through the API and the **Risk & Fraud > Signals** page in the console. > [!NOTE] > > The Anti-Fraud Identity Firewall is **generally available**. All five detection paths — direct signal ingestion, event normalization, deepfake scanning, ATO detection, and velocity scoring — are integration with multi-language API examples (cURL, JavaScript, Python), end-to-end guides, and real-time [webhook notifications](/guides/webhooks) for all signal types. Automated [risk decisions](/api-reference/risk/evaluate), [case management](#case-management), and [fraud SIEM export](#siem-export) are now available. You can create signals in five ways: * **Direct ingestion** — send a fully scored signal via `POST /v1/risk/signals` when you already have a risk score from an external provider. Supports idempotent retries via the `Idempotency-Key` header. * **Event normalization** — send a raw identity event via `POST /v1/risk/events` and let the platform map it to a signal type and base score automatically. See [event normalization](#event-normalization). * **Deepfake and impersonation signal scoring** — submit externally produced indicators or scores for threshold evaluation via `POST /v1/risk/deepfake/scan`. Scans that score 60 or above automatically ingest a risk signal. See the [deepfake detection guide](/guides/deepfake-detection). * **Account takeover detection** — evaluate login events against velocity-based heuristics via `POST /v1/risk/ato/evaluate`. Alerts are created and risk signals ingested automatically when thresholds are crossed. See the [ATO detection guide](/guides/ato-detection). * **Velocity and anomaly scoring** — record subject actions via `POST /v1/risk/velocity/record` and have the platform track frequency across rolling time windows (1 m, 5 m, 1 h, 24 h). Actions that produce a weighted velocity score of 60 or above automatically ingest a risk signal. See the [velocity scoring guide](/guides/velocity-scoring). ### Choosing an ingestion path | Scenario | Use | Endpoint | | :- | :- | :- | | You have a risk score from an external fraud tool | Direct ingestion | `POST /v1/risk/signals` | | You want platform-native events (failed logins, deepfake detections) scored automatically | Event normalization | `POST /v1/risk/events` | | You want to score supplied deepfake or impersonation indicators | Deepfake scan | `POST /v1/risk/deepfake/scan` | | You want to detect account takeover attempts based on login velocity | ATO detection | `POST /v1/risk/ato/evaluate` | | You want to detect velocity anomalies across any action type | Velocity scoring | `POST /v1/risk/velocity/record` | | You use multiple signal sources | All five — signals land in the same pipeline | Any endpoint | All five paths produce the same risk signal records. You can query, filter, and review signals from any path using the [list endpoint](/api-reference/risk-signals/list) and the **Risk & Fraud > Signals** console page. ## How it works **1. Ingest signals** Send a `POST` request to `/v1/risk/signals` with the signal source, type, risk score, and the subject it relates to. Attach any extra context in the `payload` object. **2. Query and filter** Use `GET /v1/risk/signals` to list signals with filters for source, signal type, subject, and minimum score. Results are paginated with cursor-based pagination. **3. Review in the console** Open **Risk & Fraud > Signals** in the tenant console to browse signals, filter by source or score, and inspect individual signal details. ## Prerequisites * An active Truthlocks tenant with an API key * At least one upstream fraud-detection source that produces scored signals ## Ingesting a signal Send a `POST` request with the required fields: ```bash cURL theme={null} curl -X POST https://api.truthlocks.com/v1/risk/signals \ -H "X-API-Key: tl_live_..." \ -H "Content-Type: application/json" \ -H "Idempotency-Key: $(uuidgen)" \ -d '{ "signal_source": "external", "signal_type": "velocity", "risk_score": 85, "subject_type": "user", "subject_id": "usr_8f14e45f", "payload": { "ip": "203.0.113.42", "country": "US", "reason": "multiple_accounts_same_device" }, "ip_address": "203.0.113.42" }' ``` ```javascript JavaScript theme={null} const response = await fetch("https://api.truthlocks.com/v1/risk/signals", { method: "POST", headers: { "X-API-Key": "tl_live_...", "Content-Type": "application/json", "Idempotency-Key": crypto.randomUUID(), }, body: JSON.stringify({ signal_source: "external", signal_type: "velocity", risk_score: 85, subject_type: "user", subject_id: "usr_8f14e45f", payload: { ip: "203.0.113.42", country: "US", reason: "multiple_accounts_same_device", }, ip_address: "203.0.113.42", }), }); const signal = await response.json(); ``` ```python Python theme={null} import httpx import uuid resp = httpx.post( "https://api.truthlocks.com/v1/risk/signals", headers={ "X-API-Key": "tl_live_...", "Idempotency-Key": str(uuid.uuid4()), }, json={ "signal_source": "external", "signal_type": "velocity", "risk_score": 85, "subject_type": "user", "subject_id": "usr_8f14e45f", "payload": { "ip": "203.0.113.42", "country": "US", "reason": "multiple_accounts_same_device", }, "ip_address": "203.0.113.42", }, ) signal = resp.json() ``` ### Required fields | Field | Type | Description | | :- | :- | :- | | `signal_source` | string | Origin of the signal — `verification`, `login`, `attestation`, `external`, or `manual` | | `signal_type` | string | What was detected (e.g. `velocity`, `geo_anomaly`, `device_fingerprint`, `behavior`, `deepfake`, `ato`, `impersonation`) | | `risk_score` | integer | Risk score from `0` (safe) to `100` (high risk). Scores at or above 80 trigger automatic review. | | `subject_type` | string | Type of entity: `user`, `issuer`, `attestation`, `session`, `ip`, or `device` | | `subject_id` | string | Identifier of the entity being evaluated | ### Optional fields | Field | Type | Description | | :- | :- | :- | | `payload` | object | Arbitrary JSON with signal-specific context (IP addresses, geolocation, reasons) | | `ip_address` | string | Source IP address associated with this event | | `user_agent` | string | User-Agent string associated with this event | ### Idempotency Include an `Idempotency-Key` header (UUID) to prevent duplicate signals during retries. If you send the same key twice, the duplicate is silently ignored. ## Querying signals ### List with filters ```bash theme={null} curl "https://api.truthlocks.com/v1/risk/signals?source=external&min_score=50&limit=25" \ -H "X-API-Key: tl_live_..." ``` Available filters: | Parameter | Description | | :- | :- | | `source` | Filter by signal source | | `signal_type` | Filter by signal type | | `subject_type` | Filter by subject type | | `subject_id` | Filter by subject ID | | `min_score` | Minimum score threshold (0–100) | | `limit` | Results per page (max 100) | | `cursor` | Cursor for next page | ### Get a single signal ```bash theme={null} curl https://api.truthlocks.com/v1/risk/signals/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \ -H "X-API-Key: tl_live_..." ``` ## Console view The **Risk & Fraud > Signals** page in the console provides a searchable, filterable list of all ingested signals. Each row shows the source, type, score (color-coded by severity), subject reference, and timestamp. Use the filters at the top of the page to narrow results by source, signal type, or minimum score. Click any row to view the full signal details including the `payload` metadata object. ## Scoring guidelines Consistent scoring across sources makes downstream analysis more reliable. We recommend the following ranges: | Range | Interpretation | Example | | :- | :- | :- | | 0 – 30 | Low risk | Known good device, reputable IP | | 30 – 60 | Moderate risk | VPN usage, new account velocity | | 60 – 80 | High risk | Disposable email, datacenter IP | | 80 – 100 | Critical risk | Known fraud device, impossible travel | > [!WARNING] > > Scores at or above 80 trigger automatic review decisions. Score interpretation beyond the automatic threshold is up to you — the platform stores and returns scores as-is and does not normalize across sources. ## Event normalization Instead of manually constructing risk signals, you can submit raw identity events and let the platform normalize them into signals automatically. This is useful when you want to feed platform-native events — failed logins, invalid signatures, deepfake suspects — directly into the risk pipeline without mapping them to signal types yourself. Send a `POST` request to `/v1/risk/events` with the event source, type, and subject: ```bash cURL theme={null} curl -X POST https://api.truthlocks.com/v1/risk/events \ -H "X-API-Key: tl_live_..." \ -H "Content-Type: application/json" \ -d '{ "event_source": "login", "event_type": "login.failed.repeated", "subject_id": "user_abc123", "ip_address": "198.51.100.42", "payload": { "attempt_count": 8, "window_seconds": 120 } }' ``` ```javascript JavaScript theme={null} const response = await fetch("https://api.truthlocks.com/v1/risk/events", { method: "POST", headers: { "X-API-Key": "tl_live_...", "Content-Type": "application/json", }, body: JSON.stringify({ event_source: "login", event_type: "login.failed.repeated", subject_id: "user_abc123", ip_address: "198.51.100.42", payload: { attempt_count: 8, window_seconds: 120 }, }), }); const result = await response.json(); ``` ```python Python theme={null} import httpx resp = httpx.post( "https://api.truthlocks.com/v1/risk/events", headers={"X-API-Key": "tl_live_..."}, json={ "event_source": "login", "event_type": "login.failed.repeated", "subject_id": "user_abc123", "ip_address": "198.51.100.42", "payload": {"attempt_count": 8, "window_seconds": 120}, }, ) result = resp.json() ``` The response includes both the raw `event_id` and the normalized `signal_id`, so you can trace the full pipeline from event to signal: ```json theme={null} { "event_id": "2a4b6c8d-...", "signal_id": "9f3a1c2d-...", "event_type": "login.failed.repeated", "signal_type": "ato", "risk_score": 70, "normalized": true, "created_at": "2027-05-01T10:00:00Z" } ``` When `normalized` is `true`, the event matched a known mapping. When `false`, the platform used the generic fallback. ### Built-in event mappings The platform ships with pre-calibrated mappings for common identity events: | Event type | Signal type | Base score | | :- | :- | :- | | `verification.failed` | behavior | 60 | | `verification.invalid_sig` | behavior | 75 | | `login.failed.repeated` | ato | 70 | | `login.suspicious_geo` | geo\_anomaly | 65 | | `attestation.deepfake_suspect` | deepfake | 85 | | `session.hijack_suspect` | ato | 90 | Unknown event types are accepted with signal type `behavior` and a base score of 10. ### Event fields **Required:** | Field | Type | Description | | :- | :- | :- | | `event_source` | string | System that generated the event — `attestation`, `verification`, `login`, or `consumer_portal` | | `event_type` | string | Raw event name (e.g. `login.failed.repeated`, `attestation.deepfake_suspect`) | | `subject_id` | string | Identifier of the entity involved in the event | **Optional:** | Field | Type | Description | | :- | :- | :- | | `event_ref_id` | string | External reference ID (attestation ID, session ID) for cross-referencing | | `ip_address` | string | Source IP address | | `payload` | object | Raw event payload for enrichment context | > [!NOTE] > > Use event normalization when your events originate from within the platform (logins, verifications, attestations). Use the direct [signal ingestion endpoint](/api-reference/risk/ingest-signal) when you already have a scored signal from an external source. ## Tenant isolation Risk signals are fully tenant-isolated using [row-level security (RLS)](/security/rls). Each signal is bound to the authenticated tenant at ingestion time, and queries can only return signals that belong to the calling tenant. ## Deepfake and impersonation detection The [deepfake detection API](/guides/deepfake-detection) extends the risk signal pipeline with automated scanning for manipulated content and identity fraud. Submit images, videos, documents, or attestations for analysis, and scans that exceed the risk threshold automatically create a risk signal — no extra API call needed. See the [deepfake and impersonation detection guide](/guides/deepfake-detection) for the full workflow, indicator reference, and code examples. ## Account takeover detection The [ATO detection API](/guides/ato-detection) extends the risk signal pipeline with velocity-based login monitoring. Send login events to `POST /v1/risk/ato/evaluate` and the platform tracks failed attempts per subject in a rolling one-hour window. When a subject crosses a threshold (5, 10, or 20 failed logins), an alert is created and a risk signal is automatically ingested — no extra API call needed. See the [account takeover detection guide](/guides/ato-detection) for the full workflow, threshold reference, and integration patterns. ## Velocity and anomaly scoring The [velocity scoring API](/guides/velocity-scoring) extends the risk signal pipeline with multi-window action tracking and anomaly detection. Record any subject action via `POST /v1/risk/velocity/record` and the platform tracks frequency across four rolling windows (1 m, 5 m, 1 h, 24 h). A weighted velocity score is computed from the window counts, biased toward short windows for burst detection. When the score reaches 60 or above, a risk signal with `signal_type: "velocity"` is automatically ingested — no extra API call needed. See the [velocity and anomaly scoring guide](/guides/velocity-scoring) for the full workflow, scoring model, and integration patterns. ## Webhook notifications Risk signals created by any of the five detection paths can trigger real-time [webhook](/guides/webhooks) notifications. Subscribe to `risk.signal.created` or `risk.signal.escalated` to react to new signals without polling. This covers signals from direct ingestion, event normalization, deepfake scans, ATO alerts, and velocity anomalies. See the [webhooks guide](/guides/webhooks#risk-signal-notifications) for payload examples and integration patterns. ## Usage metering Anti-Fraud features are metered per billing cycle. Each detection path increments its own usage counter: | Metric | Metered action | | :- | :- | | `antifraud.risk_signals` | Risk signals ingested or generated (all five paths) | | `antifraud.deepfake_scans` | Deepfake and impersonation scan requests | | `antifraud.velocity_records` | Velocity scoring action records | Quotas vary by plan tier. You can check your current consumption with the [usage API](/api-reference/billing/usage) or in the console at **Settings > Billing > Usage** under the **Anti-Fraud** section. To verify whether a specific operation is allowed before performing it, use the [limit check endpoint](/api-reference/billing/entitlements). ```bash theme={null} curl https://api.truthlocks.com/v1/billing/usage \ -H "X-API-Key: tl_live_..." ``` The response includes all Anti-Fraud counters with `used`, `limit`, and `period` fields so you can monitor consumption programmatically. > [!NOTE] > > See the [billing overview](/billing/overview#metered-products) for the full list of 16 metered products and their default rates. ## What's next * [Velocity and anomaly scoring guide](/guides/velocity-scoring) * [Account takeover detection guide](/guides/ato-detection) * [Deepfake and impersonation detection guide](/guides/deepfake-detection) * [Ingest risk signal API reference](/api-reference/risk-signals/ingest) * [Normalize identity event API reference](/api-reference/risk/normalize-event) * [List risk signals API reference](/api-reference/risk-signals/list) * [Get risk signal API reference](/api-reference/risk-signals/get) * [Row-level security](/security/rls) # Integration Examples Source: https://docs.truthlocks.com/guides/sdk-examples A direct HTTP mint example with explicit encoding and idempotency. This example uses Node.js's built-in `fetch` to make the HTTP contract explicit. It does not depend on an SDK release. SDK versions can have different models and authentication options; check the installed version before adapting examples. ## Prerequisites Use an API key, issuer, and available managed signing key from the same environment. Public-key registration alone does not provision a private signing key. Complete [workspace setup](/quickstart) first. ## Mint with Node.js Save as `mint.mjs`. Configure the environment variables below through your shell or secret manager, then run `node mint.mjs` with a Node.js version supporting `fetch`. ```javascript theme={null} import { randomUUID } from 'node:crypto'; const required = name => { const value = process.env[name]; if (!value) throw new Error(`Set ${name}`); return value; }; const baseUrl = (process.env.TRUTHLOCKS_BASE_URL ?? 'https://sandbox-api.truthlocks.com').replace(/\/$/, ''); const payload = Buffer.from(JSON.stringify({ subject: 'demo-record', message: 'Example issuer claim' }), 'utf8'); const body = { issuer_id: required('TRUTHLOCKS_ISSUER_ID'), kid: required('TRUTHLOCKS_KEY_ID'), alg: required('TRUTHLOCKS_ALGORITHM'), content_type: 'application/json', payload_b64url: payload.toString('base64url'), }; // Persist this value with the body before issuing requests in a durable job. const idempotencyKey = randomUUID(); const response = await fetch(`${baseUrl}/v1/attestations/mint`, { method: 'POST', headers: { 'Content-Type': 'application/json', 'X-API-Key': required('TRUTHLOCKS_API_KEY'), 'Idempotency-Key': idempotencyKey, }, body: JSON.stringify(body), signal: AbortSignal.timeout(30000), }); if (!response.ok) throw new Error(`Mint failed: HTTP ${response.status}`); const record = await response.json(); console.log({ attestationId: record.attestation_id, recordedAt: record.issued_at_unix }); ``` Retain the original body and idempotency key when retrying after a timeout. This short example does not implement persistent jobs or automatic retries. Avoid logging API keys, private payloads, or raw responses containing personal data. ## Verify and interpret results Submit the returned ID to [Verify](/api-reference/verify). Add the original `payload_b64url` if you want to check the exact bytes. Inspect `verdict` and `reasons`; HTTP 200 alone does not establish validity. The signature proves a cryptographic relationship to the signing key. It does not independently verify the real-world truth of the submitted claims. For Python's standard-library version, see the [quickstart](/quickstart). For revocation and replacement, follow the generated request contracts for [revoke](/api-reference/attestations/revoke) and [supersede](/api-reference/attestations/supersede); do not reuse a mint body for those operations. # SIEM audit delivery Source: https://docs.truthlocks.com/guides/siem-integration Configure scoped audit delivery, verify webhooks, and understand coverage and retries. Use the [destination API](/api-reference/audit/siem/create) to save encrypted configuration for Splunk, Datadog, Elastic or an HTTPS webhook. First [list destinations](/api-reference/audit/siem/list): `delivery_available` must be `true` before you enable delivery. A deployment without the worker returns `409 DELIVERY_UNAVAILABLE` when you request `enabled: true`. ## What is delivered An enabled destination receives **new audit events whose workspace and environment were verified when recorded**. A production destination never receives sandbox events. Historical events and events without reliable environment attribution are not assigned a guessed environment or streamed. This does not promise that every legacy producer records every platform action; use recorded audit/export evidence to identify coverage gaps. Configuration is not proof of ingestion. `status: enabled` means the destination is enabled. The list response includes environment-wide `delivery_counts` for `pending`, `delivered`, `failed` and `cancelled` records. A delivered record has received the provider's HTTP acknowledgement; downstream indexing, alerts and retention must also be checked in your SIEM. ## Configure the receiver Use a public HTTPS hostname on port 443, without credentials in the URL, query parameters or fragments. Private addresses, redirects and non-HTTPS endpoints are rejected. Each workspace environment supports up to 20 destinations. | Provider | Endpoint | Credential and delivery | | - | - | - | | Webhook | Your HTTPS ingestion URL | Supply `secret`. Receives a JSON envelope and timestamped HMAC-SHA256 signature. | | Splunk | HTTPS HEC event endpoint, normally `/services/collector/event` | Supply a HEC `token`. Uses `Authorization: Splunk …`; HTTP success must also contain `code: 0`. Use port 443 or an appropriate HTTPS reverse proxy. | | Datadog | Your site's HTTPS `/api/v2/logs` endpoint | Supply a log-ingestion API `token`. Uses `DD-API-KEY` and a JSON log array. Select the correct Datadog site. | | Elastic | Your HTTPS endpoint ending in `/INDEX/_doc` | Supply the encoded API-key `token`. Uses `Authorization: ApiKey …` and a deterministic document ID. | Provider contracts: [Splunk HEC](https://help.splunk.com/splunk-enterprise/get-data-in/get-started-with-getting-data-in/9.1/get-data-with-http-event-collector/format-events-for-http-event-collector), [Datadog logs](https://docs.datadoghq.com/api/latest/logs/), [Elasticsearch indexing](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-index). Protocol support does not establish that your provider account has accepted an event; test the configured account. Supply `secret` for webhooks or `token` for the other providers, never both. Credentials are encrypted at rest and never returned. Changing an endpoint requires providing its credential again. Use a dedicated credential with ingestion-only privileges where supported. ## Verify webhook signatures The JSON envelope includes `id`, `tenant_id`, `environment_id`, `occurred_at` and `event`. The `X-Truthlocks-Event-ID` header repeats the event ID. Verify the exact HTTP body bytes before parsing or processing them: ```python theme={null} import hashlib import hmac import time def verify_webhook(raw_body: bytes, headers, secret: bytes) -> bool: timestamp = headers.get("X-Truthlocks-Timestamp", "") try: if abs(time.time() - int(timestamp)) > 300: return False signed = timestamp.encode("ascii") + b"." + raw_body except (ValueError, TypeError, UnicodeEncodeError): return False expected = "v1=" + hmac.new(secret, signed, hashlib.sha256).hexdigest() return hmac.compare_digest( expected, headers.get("X-Truthlocks-Signature", "") ) ``` Accept only the expected workspace/environment and record event IDs durably to reject replays. Return a 2xx response only after accepting the event into durable storage. Use constant-time signature comparison; do not log the shared secret or authentication headers. ## Retries and configuration changes Delivery is at least once. The queue is committed in the same database transaction as the attributed audit event, so an audit rollback cannot leave a delivery behind. A worker crash after receiver acceptance can cause a duplicate; deduplicate using the stable event ID. Transport failures and non-2xx responses retry with exponential backoff starting at one minute, capped at one hour, up to 20 attempts. Exhausted records remain `failed`; there is no automatic unlimited retry or promised completion time. Disabling or changing a destination cancels its pending deliveries to avoid forwarding an old backlog to a changed receiver. Deletion removes configuration, the saved credential and its delivery queue records. Preserve required delivery evidence before deletion. There is no automatic historical replay. ## Snapshot exports Use [audit exports](/api-reference/audit/export) for recorded audit snapshots and [risk-event exports](/api-reference/risk/exports/create) for supported risk-signal snapshots. Persist processing position and deduplicate event identities when importing snapshots. Export jobs, SIEM delivery and downstream alerting are separate operations; completing one does not prove the others succeeded. # Subscription management Source: https://docs.truthlocks.com/guides/subscription-management Choose a plan, subscribe via checkout, manage add-ons, and handle cancellation using the API or console. You can manage your entire billing lifecycle through the API or the console. This guide covers how to list plans, estimate costs, create a checkout session, check your subscription, attach add-ons, and cancel when needed. ## Prerequisites * A Truthlocks account with an active tenant. * An API key with billing permissions. See [API keys](/api-reference/api-keys/create) to create one. ## Choose a plan Truthlocks offers five plan tiers. Use the plans endpoint to fetch the full catalog — this is a public endpoint and does not require authentication. ```bash theme={null} curl https://api.truthlocks.com/v1/billing/plans ``` ```json theme={null} [ { "key": "plan_developer", "name": "Developer", "price": 0, "currency": "USD", "interval": "month", "features": ["500 mints/month", "Plan-dependent verifications", "Community support"], "highlight": false }, { "key": "plan_starter", "name": "Starter", "price": 29, "currency": "USD", "interval": "month", "features": ["Higher quotas", "3 webhook endpoints", "Priority processing"], "highlight": true } ] ``` See [billing overview](/billing/overview#plan-tiers) for a comparison of all plans. ## Estimate your costs Before subscribing, use the estimate endpoint to get a plan recommendation based on your expected usage. This is also a public endpoint. ```bash theme={null} curl -X POST https://api.truthlocks.com/v1/billing/estimate \ -H "Content-Type: application/json" \ -d '{ "country_code": "US", "expected_verifications_monthly": 10000, "team_seats": 5, "webhook_endpoints_needed": 5, "storage_gb": 10 }' ``` The response includes a recommended plan and estimated monthly total. For a line-item cost breakdown, use the [projected invoice](/api-reference/billing/projected-invoice) endpoint instead. ## Check your current rates Your tenant's effective per-use rates depend on your rate card and region. Fetch them with: ```bash theme={null} curl https://api.truthlocks.com/v1/billing/rates \ -H "X-API-Key: tl_live_..." ``` The response includes base rates and any regional pricing adjustments: ```json theme={null} { "rate_card": { "id": "rc_default", "name": "Standard Rates", "currency": "USD" }, "items": [ { "metric": "attestations.mint", "unit_price": 25, "volume_min": 0, "volume_max": 0 }, { "metric": "verifications", "unit_price": 10, "volume_min": 0, "volume_max": 0 } ], "is_default": true, "regional_rates": { "region": "TIER_1", "multiplier": 1.0, "mint_rate_cents": 25, "verify_rate_cents": 10 } } ``` > [!NOTE] > > If your organization has a custom rate card assigned by a platform admin, those rates appear here instead of the defaults. ## Subscribe to a plan Create a checkout session to start or upgrade your subscription. The billing service selects the correct payment provider for your region automatically. **1. Create a checkout session** Call the checkout endpoint with the plan you want and redirect URLs: ```bash theme={null} curl -X POST https://api.truthlocks.com/v1/billing/checkout \ -H "X-API-Key: tl_live_..." \ -H "Content-Type: application/json" \ -d '{ "plan_key": "STARTER", "success_url": "https://yourapp.com/billing?success=true", "cancel_url": "https://yourapp.com/billing?canceled=true" }' ``` The response contains a `checkout_url` hosted by the payment provider. **2. Redirect to checkout** Send the user to the `checkout_url` to complete payment. ```javascript theme={null} const res = await fetch("https://api.truthlocks.com/v1/billing/checkout", { method: "POST", headers: { "X-API-Key": "tl_live_...", "Content-Type": "application/json", }, body: JSON.stringify({ plan_key: "STARTER", success_url: `${window.location.origin}/billing?success=true`, cancel_url: `${window.location.origin}/billing?canceled=true`, }), }); const { checkout_url } = await res.json(); window.location.href = checkout_url; ``` **3. Confirm the subscription** After payment, verify the subscription is active: ```bash theme={null} curl https://api.truthlocks.com/v1/billing/subscription \ -H "X-API-Key: tl_live_..." ``` ```json theme={null} { "status": "active", "plan_key": "plan_starter", "current_period_end": "2026-05-01T00:00:00Z", "cancel_at_period_end": false } ``` > [!TIP] > > You can optionally pass a `provider` parameter (`stripe`, `paystack`, or `flutterwave`) to override automatic region-based routing. See [provider routing](/billing/provider-routing) for details. ## Attach add-ons Add-ons extend your plan with extra capabilities. Attach them via the API: ```bash theme={null} curl -X POST https://api.truthlocks.com/v1/billing/addons/attach \ -H "X-API-Key: tl_live_..." \ -H "Content-Type: application/json" \ -d '{ "addon_key": "addon_seat", "quantity": 2 }' ``` If the add-on has a price, the response includes a `checkout_url` to complete payment. Free add-ons activate immediately. > [!NOTE] > > Add-on prices adjust automatically based on your organization's billing country. Tenants in lower-cost regions pay a reduced rate — for example, the Compliance Pack costs $149.50/month in Nigeria (0.5x multiplier) instead of the $299 base price. See [regional add-on pricing](/billing/overview#regional-add-on-pricing) for the full tier table. To remove an add-on: ```bash theme={null} curl -X POST https://api.truthlocks.com/v1/billing/addons/detach \ -H "X-API-Key: tl_live_..." \ -H "Content-Type: application/json" \ -d '{"addon_key": "addon_seat"}' ``` See [manage add-ons](/api-reference/billing/addons) for the full add-on catalog and response details. ## Monitor usage Track your current billing cycle consumption to stay within your plan limits: ```bash theme={null} curl https://api.truthlocks.com/v1/billing/usage \ -H "X-API-Key: tl_live_..." ``` To check whether a specific operation is within quota before performing it: ```bash theme={null} curl -X POST https://api.truthlocks.com/v1/billing/limits/check \ -H "X-API-Key: tl_live_..." \ -H "Content-Type: application/json" \ -d '{"metric": "attestations.mint", "amount": 1}' ``` ## Open the billing portal Redirect users to their payment provider's self-service portal to update payment methods, view invoices, or manage their subscription: ```bash theme={null} curl -X POST https://api.truthlocks.com/v1/billing/portal \ -H "X-API-Key: tl_live_..." \ -H "Content-Type: application/json" \ -d '{ "return_url": "https://yourapp.com/settings/billing" }' ``` The response includes a `portal_url`. Redirect the user to that URL. Portal sessions expire quickly, so generate a fresh URL each time. ## Cancel a subscription To cancel, call the cancel endpoint. The cancellation takes effect at the end of the current billing period — you keep full access until then. ```bash theme={null} curl -X POST https://api.truthlocks.com/v1/billing/cancel \ -H "X-API-Key: tl_live_..." ``` ```json theme={null} { "status": "active", "plan_key": "plan_starter", "current_period_end": "2026-05-01T00:00:00Z", "cancel_at_period_end": true } ``` After the period ends, your account downgrades to the Developer (free) plan. To resubscribe, create a new [checkout session](/api-reference/billing/checkout). > [!WARNING] > > You cannot undo a cancellation via the API. To resume your subscription, you need to go through checkout again. ## Related > **[Billing overview](/billing/overview)** > > Plan tiers, rates, entitlements, and add-ons. > **[Provider routing](/billing/provider-routing)** > > How payments are routed by region. > **[Billing API reference](/api-reference/billing/config)** > > Full billing API endpoint reference. > **[Entitlements](/api-reference/billing/entitlements)** > > Check your active features and quotas. # Transparency settings Source: https://docs.truthlocks.com/guides/transparency-settings Control your organization's public profile on the Trust Explorer directory. Transparency settings let you manage how your organization appears on the public [Trust Explorer](https://transparency.truthlocks.com) directory. When enabled, verifiers can look up your organization and confirm that attestations were issued by a legitimate, publicly listed entity. ## Prerequisites * An active Truthlocks tenant with at least one issuer * Tenant admin or owner role ## What the Trust Explorer shows The Trust Explorer is a public portal where anyone can browse the transparency log, search attestations, and view issuer profiles. When you opt in to the public directory, your organization's profile is listed at `transparency.truthlocks.com/issuers/ORGANIZATION_SLUG`. Your public profile displays: | Field | Description | | - | - | | Display name | Your organization's public-facing name | | Website | Link to your official site | | Logo | Your organization logo (PNG, JPEG, SVG, or WebP — max 2 MB) | | Verification tier | Whether your organization has been verified | | Status | Current tenant status (active or pending) | > [!NOTE] > > The Trust Explorer only shows structural data — Merkle roots, tree sizes, and cryptographic signatures. No attestation content, PII, or sensitive data is ever exposed. ## Configure transparency settings **1. Open transparency settings** In the console, go to **Settings > Transparency**. **2. Opt in to the public directory** Toggle **Opt-in to Public Directory** on. When enabled, your organization name, website, and verification status appear in the Trust Explorer issuer directory. **3. Set your profile details** Fill in your public display name, official website URL, and upload a logo. The logo can be uploaded directly (max 2 MB) or provided as a URL. **4. Save changes** Click **Save Changes** to publish your profile. ## Latest checkpoint The transparency settings page also shows your latest transparency log checkpoint. This gives you a quick health check on the log without leaving the console: * **Tree size** — total entries in the Merkle tree * **Signed at** — when the checkpoint was signed * **Root hash** — the Merkle root hash for this checkpoint * **Signer** — the key ID that signed the checkpoint For a detailed view of all checkpoints and search capabilities, visit the [Truth Explorer](/guides/truth-explorer). ## Verification tiers Your verification tier determines the trust badge shown on your public profile: | Tier | Meaning | | - | - | | **Verified** | Your organization has completed the governance review process and holds a higher trust tier | | **Basic** | Your organization is active with the default trust level assigned on issuer creation | The verification tier is set automatically based on your issuer's trust level. New issuers start at **Basic** and can issue attestations immediately. To upgrade to a higher tier, submit an [issuer application](/guides/issuer-applications) for review. ## Transparency settings API You can also read and update transparency settings through the API: ```bash theme={null} # Get current transparency settings curl https://api.truthlocks.com/v1/settings/transparency \ -H "X-API-Key: tl_live_..." ``` ```bash theme={null} # Update transparency settings curl -X PUT https://api.truthlocks.com/v1/settings/transparency \ -H "X-API-Key: tl_live_..." \ -H "Content-Type: application/json" \ -d '{ "is_public": true, "display_name": "Acme Corp", "website": "https://acme.com", "logo_url": "https://acme.com/logo.png", "verification_tier": "verified" }' ``` ## Privacy considerations Opting in to the public directory is entirely voluntary. When disabled: * Your organization does not appear in the issuer directory * Attestations you issue are still valid and verifiable by ID * Verifiers can still check individual attestation signatures, but cannot browse your profile When enabled, only the information you configure (display name, website, logo) is shown. Internal details like contact email, region, and tenant type are never exposed on the public profile. ## Related > **[Truth Explorer](/guides/truth-explorer)** > > Browse the public transparency log, validate proof bundles, and search attestations. > **[Enterprise branding](/guides/enterprise-branding)** > > Customize your organization's branding across the console and verify portal. # Trust Scores Source: https://docs.truthlocks.com/guides/trust-scores Continuous behavioral trust evaluation for AI agents with configurable scoring factors. # Trust Scores Trust scores provide a **continuous, real-time assessment** of an AI agent's behavioral reliability. Every agent in the Truthlocks platform receives a score from 0 to 100, updated after each action. ## How It Works ``` Agent Action → Event Logged → Score Recomputed → Policy Evaluated │ ┌─────┴─────┐ │ Score: 87 │ │ Trend: ↑ │ └────────────┘ │ ┌───────────┼───────────┐ ▼ ▼ ▼ No Action Alert Team Suspend Agent (score > 70) (50 < s < 70) (score < 50) ``` > [!TIP] > > All trust score and witness endpoints have an interactive API playground. Open any endpoint in the [Trust & Witness](/api-reference/machine-identity/trust-scores/get) API reference and click **Send** to try it live. ## Scoring factors | Factor | Default Weight | Description | | - | - | - | | `behavioral_compliance` | 35% | Actions stay within declared scope boundaries | | `scope_adherence` | 25% | No attempts to access unauthorized resources | | `anomaly_score` | 20% | Statistical deviation from historical behavior patterns | | `peer_attestations` | 10% | Other agents in the witness network vouch for behavior | | `session_hygiene` | 10% | Proper session lifecycle (creation, renewal, termination) | ## Reading Trust Scores ### Get Current Score ```bash theme={null} curl https://api.truthlocks.com/v1/trust-scores/maip-agent:01JXXXX \ -H "X-API-Key: $API_KEY" ``` ```json theme={null} { "agent_id": "maip-agent:01JXXXX", "score": 87, "factors": { "behavioral_compliance": 92, "scope_adherence": 95, "anomaly_score": 12, "peer_attestations": 78, "session_hygiene": 90 }, "trend": "stable", "computed_at": "2026-04-06T12:00:00Z" } ``` ### Get Score History ```bash theme={null} curl "https://api.truthlocks.com/v1/trust-scores/maip-agent:01JXXXX/history?period=7d" \ -H "X-API-Key: $API_KEY" ``` ### Force Recomputation ```bash theme={null} curl -X POST https://api.truthlocks.com/v1/trust-scores/maip-agent:01JXXXX/compute \ -H "X-API-Key: $API_KEY" ``` ## Configuring Thresholds | Threshold | Recommended Action | | - | - | | 90-100 | Full autonomy — agent operates without intervention | | 70-89 | Standard operation — normal monitoring | | 50-69 | Enhanced monitoring — alert team, increase logging verbosity | | 30-49 | Restricted mode — require human approval for critical actions | | 0-29 | Automatic suspension — kill switch triggered | ## Witness Network Agents can participate in a **witness network** where peers attest to each other's behavior. ### Create a Witness Request ```bash theme={null} curl -X POST https://api.truthlocks.com/v1/witness/request \ -H "X-API-Key: $API_KEY" \ -d '{ "subject_agent_id": "maip-agent:01JXXXX", "claim": "Completed invoice processing without errors", "evidence": { "task_id": "task_456", "records_processed": 150 } }' ``` ### Attest as Witness ```bash theme={null} curl -X POST https://api.truthlocks.com/v1/witness/maip-witness:01JWWWW/attest \ -H "X-API-Key: $API_KEY" \ -d '{ "attestor_agent_id": "maip-agent:01JBBBB", "verdict": "confirmed", "confidence": 0.95 }' ``` ### Consensus ```bash theme={null} curl -X POST https://api.truthlocks.com/v1/witness/maip-witness:01JWWWW/consensus \ -H "X-API-Key: $API_KEY" ``` ```json theme={null} { "witness_id": "maip-witness:01JWWWW", "consensus": "confirmed", "confidence": 0.91, "attestations": 4, "quorum_met": true } ``` ## Integration with Risk Engine Trust scores feed directly into the Truthlocks risk evaluation engine. Low trust scores automatically increase the risk signal for any action the agent takes: ``` Trust Score < 50 → Risk Signal: HIGH → Action blocked or requires approval ``` ## Usage metering Each on-demand trust score computation increments the `maip.trust_computes` usage counter for your billing cycle. Background score updates triggered by the platform (such as after agent actions) also count toward this metric. You can monitor your consumption with the [usage API](/api-reference/billing/usage) or in the console at **Settings > Billing > Usage** under the **MAIP** section. > [!NOTE] > > Trust score compute quotas vary by plan tier. See the [billing overview](/billing/overview#metered-products) for details on all MAIP metered products. ## Next steps > **[Machine Identity](/guides/machine-identity)** > > Full overview of the Machine Agent Identity Protocol. > **[Cross-Tenant Delegation](/guides/cross-tenant-delegation)** > > Enable agents to operate across organizational boundaries. # Truth Explorer Source: https://docs.truthlocks.com/guides/truth-explorer Browse checkpoints, search the transparency log, validate proof bundles, and view issuer profiles. The [Truth Explorer](https://transparency.truthlocks.com) is a public portal for inspecting the Truthlocks transparency log. Anyone can browse checkpoints, search by attestation ID or leaf hash, validate proof bundles offline, and view the issuer directory — no account required. Use it to independently verify that an attestation exists in the append-only Merkle tree, confirm checkpoint integrity, or audit issuer trust status. ## Checkpoint timeline The home page shows a live timeline of every checkpoint recorded in the transparency log. Each row displays: | Column | Description | | :- | :- | | Checkpoint | The tree size at the time of the checkpoint, linking to its detail page | | Age | How long ago the checkpoint was signed | | Root hash | The Merkle root hash (truncated, with copy-to-clipboard) | | Signer | The key ID of the signer | | Status | Whether the checkpoint carries a valid signature | Four summary cards at the top show the current **tree size**, log **status**, total **checkpoints**, and the age of the **latest** checkpoint. ## Searching the log Type an attestation ID or leaf hash into the search bar at the top of the timeline. The search auto-detects the query type: * **Attestation ID** — any non-hex string that identifies a specific attestation. * **Leaf hash** — a hex string (16+ characters) identifying a leaf in the Merkle tree. When a match is found, you see the attestation ID, leaf index, event type, and a link to the corresponding checkpoint. ## Checkpoint details Click any checkpoint number to open a detail view. The page shows: * **Tree size** — number of leaves at this checkpoint. * **Timestamp** — when the checkpoint was recorded. * **Merkle root hash** — the full hex root hash with a copy button. * **Signature** — the Ed25519 signature (if signed). * **Signer key ID** — the key that signed the checkpoint. * **Log ID** — the unique identifier for this log instance. > [!NOTE] > > Checkpoint details confirm log integrity without revealing individual attestation contents. The transparency log is an append-only structure — once a leaf is anchored, it cannot be modified or removed. ## Validating proof bundles The `/validate` page lets you verify a proof bundle entirely in your browser. No data is sent to any server. **1. Upload a proof bundle** Drag and drop (or click to select) a `proof-bundle.json` file. The maximum file size is 5 MB. **2. Review the four-step verification** The validator runs four checks automatically: 1. **JSON schema and content integrity** — parses the bundle, verifies the `bundle_hash_b64url` integrity hash, and cross-checks attestation and log metadata. 2. **SHA-256 Merkle inclusion proof** — recomputes the Merkle root from the leaf hash and audit path using the RFC 6962 algorithm, then compares it to the root hash in the checkpoint. 3. **Ed25519 checkpoint signature** — verifies the checkpoint signature against the signing public key using the Web Crypto API. 4. **Network confirmation** — fetches the live checkpoint from the transparency log API and compares root hashes. **3. Read the verdict** A pass/fail banner appears at the top, followed by a step-by-step checklist and summary cards showing the attestation ID, leaf index, and tree size. > [!TIP] > > Steps 1–3 run entirely offline using browser-native cryptography. Step 4 contacts the transparency log API to confirm the checkpoint is still live. If you are offline, the first three checks still provide integrity checks against the supplied trusted keys and checkpoint. ## Issuer directory The `/issuers` page lists every issuer in the Truthlocks trust registry that has opted in to the public directory. You can filter by name or issuer ID. Each entry shows: * **Name and logo** — with a **Verified** badge for issuers that have completed governance review. * **Website** — a link to the issuer's public site. * **Verification tier** — **Basic** (default for new issuers) or **Verified** (assigned after governance review). See [transparency settings](/guides/transparency-settings#verification-tiers) for details. Click an issuer to view their full profile, including their issuer ID, verification tier, status, and when they were registered. To upgrade from Basic to Verified, submit an [issuer application](/guides/issuer-applications). Issuers with a private profile show a note that their signatures are valid but identity details are not public. ## When to use Truth Explorer | Scenario | What to do | | :- | :- | | Verify a proof bundle someone shared with you | Go to `/validate` and upload the `proof-bundle.json` file | | Check whether a specific attestation is in the log | Search by attestation ID on the home page | | Audit the log's checkpoint history | Browse the checkpoint timeline or click into a specific checkpoint | | Look up an issuer's trust status | Open the `/issuers` directory and search by name or ID | ## Related > **[Proof bundle specification](/specification/proof-bundle)** > > Schema and field reference for `proof-bundle.json`. > **[Content protection](/guides/content-protection)** > > How to protect content and generate proof bundles. # Velocity and anomaly scoring Source: https://docs.truthlocks.com/guides/velocity-scoring Track action frequency across rolling time windows, detect velocity anomalies, and auto-ingest risk signals when thresholds are exceeded. The velocity and anomaly scoring API tracks how frequently a subject performs a given action across multiple rolling time windows — 1 minute, 5 minutes, 1 hour, and 24 hours. When the weighted velocity score crosses a threshold, the platform automatically creates a [risk signal](/guides/risk-signals), connecting anomaly detection directly to the Anti-Fraud Identity Firewall pipeline. > [!NOTE] > > Velocity scoring is part of the [Anti-Fraud Identity Firewall](/guides/risk-signals). Signals generated by velocity anomalies flow into the same pipeline as other fraud signals, so you can query and review them from the **Risk & Fraud > Signals** console page or the [list signals endpoint](/api-reference/risk-signals/list). ## How it works **1. Record actions** Call `POST /v1/risk/velocity/record` each time a subject performs a tracked action — login attempts, API calls, transaction requests, or any custom action type. **2. Rolling window tracking** The platform increments counters for the subject and action type across four rolling windows (1 m, 5 m, 1 h, 24 h). Windows reset automatically when they expire. **3. Weighted scoring** A velocity score is computed from the window counts. Short windows are weighted more heavily to detect bursts: 1 m × 30, 5 m × 20, 1 h × 10, 24 h × 5. **4. Automatic signal ingestion** When the velocity score reaches 60 or above, the platform automatically ingests a risk signal with `signal_type: "velocity"`. You don't need a separate API call. **5. Review and respond** Query velocity windows for a subject, list high-velocity anomalies across your tenant, and review signals in the console or via the API. ## Prerequisites * An active Truthlocks tenant with an API key * Action event data from your application (login attempts, API calls, transactions, or any repeatable action) ## Recording an action Send a `POST` request to `/v1/risk/velocity/record` with the subject, action type, and optional metadata: ```bash cURL theme={null} curl -X POST https://api.truthlocks.com/v1/risk/velocity/record \ -H "X-API-Key: tl_live_..." \ -H "Content-Type: application/json" \ -d '{ "subject_id": "user_abc123", "action_type": "login.failed", "ip_address": "198.51.100.42" }' ``` ```javascript JavaScript theme={null} const response = await fetch("https://api.truthlocks.com/v1/risk/velocity/record", { method: "POST", headers: { "X-API-Key": "tl_live_...", "Content-Type": "application/json", }, body: JSON.stringify({ subject_id: "user_abc123", action_type: "login.failed", ip_address: "198.51.100.42", }), }); const result = await response.json(); ``` ```python Python theme={null} import httpx resp = httpx.post( "https://api.truthlocks.com/v1/risk/velocity/record", headers={"X-API-Key": "tl_live_..."}, json={ "subject_id": "user_abc123", "action_type": "login.failed", "ip_address": "198.51.100.42", }, ) result = resp.json() ``` The response returns the current window counts, the computed velocity score, and whether a risk signal was auto-ingested: ```json theme={null} { "subject_id": "user_abc123", "action_type": "login.failed", "windows": { "1m": 3, "5m": 8, "1h": 15, "24h": 42 }, "velocity_score": 72, "signal_ingested": true, "signal_id": "a1b2c3d4-..." } ``` ## Scoring model The velocity score is a weighted sum of action counts across four rolling windows. Short windows carry higher weight to prioritize burst detection: | Window | Weight | Purpose | | :- | :- | :- | | 1 minute | 30 | Detects rapid bursts (credential stuffing, automated attacks) | | 5 minutes | 20 | Catches sustained short-term abuse | | 1 hour | 10 | Identifies medium-term patterns | | 24 hours | 5 | Flags persistent anomalies over longer periods | The final score is capped at 100. When the score reaches **60 or above**, a risk signal is automatically ingested with `signal_type: "velocity"`. ### Score interpretation | Score range | Interpretation | Example | | :- | :- | :- | | 0–29 | Normal | Typical user activity | | 30–59 | Elevated | Above-average frequency, worth monitoring | | 60–79 | High | Likely automated or abusive — signal auto-ingested | | 80–100 | Critical | Strong anomaly — immediate investigation recommended | ## Querying velocity windows Retrieve the current velocity windows for a specific subject: ```bash cURL theme={null} curl https://api.truthlocks.com/v1/risk/velocity/user_abc123 \ -H "X-API-Key: tl_live_..." ``` ```javascript JavaScript theme={null} const response = await fetch("https://api.truthlocks.com/v1/risk/velocity/user_abc123", { headers: { "X-API-Key": "tl_live_..." }, }); const windows = await response.json(); ``` ```python Python theme={null} import httpx resp = httpx.get( "https://api.truthlocks.com/v1/risk/velocity/user_abc123", headers={"X-API-Key": "tl_live_..."}, ) windows = resp.json() ``` The response includes all tracked action types for the subject, with counts per window and the computed velocity score for each: ```json theme={null} { "subject_id": "user_abc123", "actions": [ { "action_type": "login.failed", "windows": { "1m": 0, "5m": 2, "1h": 8, "24h": 23 }, "velocity_score": 45 }, { "action_type": "api.request", "windows": { "1m": 12, "5m": 45, "1h": 200, "24h": 800 }, "velocity_score": 87 } ] } ``` ## Listing high-velocity anomalies Query subjects with velocity scores above a threshold across your tenant: ```bash cURL theme={null} curl "https://api.truthlocks.com/v1/risk/velocity?min_score=50&limit=25" \ -H "X-API-Key: tl_live_..." ``` ```javascript JavaScript theme={null} const response = await fetch( "https://api.truthlocks.com/v1/risk/velocity?min_score=50&limit=25", { headers: { "X-API-Key": "tl_live_..." } } ); const anomalies = await response.json(); ``` ```python Python theme={null} import httpx resp = httpx.get( "https://api.truthlocks.com/v1/risk/velocity", params={"min_score": 50, "limit": 25}, headers={"X-API-Key": "tl_live_..."}, ) anomalies = resp.json() ``` Each result includes the subject, action type, current window counts, and the velocity score that qualified the anomaly: ```json theme={null} { "anomalies": [ { "subject_id": "user_abc123", "action_type": "login.failed", "windows": { "1m": 5, "5m": 12, "1h": 30, "24h": 85 }, "velocity_score": 68, "last_recorded_at": "2027-07-03T14:22:00Z" } ], "cursor": "eyJsYXN0X2lkIjo..." } ``` ## Integration patterns ### Block or throttle on high velocity Use the velocity score from the record response to decide whether to allow, throttle, or block an action: ```javascript theme={null} const result = await recordAction(subjectId, "api.request", ipAddress); if (result.velocity_score >= 80) { await blockSubject(subjectId); await notifySecurityTeam(result); } else if (result.velocity_score >= 60) { await throttleRequests(subjectId, { maxPerMinute: 5 }); } else if (result.velocity_score >= 30) { await addRateLimitWarning(subjectId); } ``` ### Combine with ATO detection Velocity scoring tracks any action type across multiple time windows, while [ATO detection](/guides/ato-detection) is specifically optimized for login-based account takeover patterns with built-in threshold rules and alert management. Use both together for layered protection: * **Velocity scoring** for general abuse detection — API rate abuse, transaction flooding, registration spam * **ATO detection** for focused login security — failed login velocity, credential stuffing alerts, subject risk profiles ### Monitor via webhooks Configure a [webhook endpoint](/guides/webhooks) to receive real-time notifications when velocity-based risk signals are created, so your security team can respond without polling. ### Custom action types You can track any action type your application produces. Common examples: | Action type | Use case | | :- | :- | | `login.failed` | Failed login attempts | | `api.request` | API call frequency | | `transaction.create` | Payment or transfer attempts | | `registration.attempt` | Account creation spam | | `password.reset` | Password reset abuse | | `verification.request` | Verification request flooding | ## Usage metering Each call to `POST /v1/risk/velocity/record` increments the `antifraud.velocity_records` usage counter for your billing cycle. You can monitor your consumption with the [usage API](/api-reference/billing/usage) or in the console at **Settings > Billing > Usage** under the **Anti-Fraud** section. > [!NOTE] > > Velocity record quotas vary by plan tier. See the [billing overview](/billing/overview#metered-products) for details on all Anti-Fraud metered products. ## What's next * [Record velocity action API reference](/api-reference/risk/velocity-record) * [Get velocity windows API reference](/api-reference/risk/velocity-windows) * [List velocity anomalies API reference](/api-reference/risk/velocity-anomalies) * [Risk signals guide](/guides/risk-signals) * [Account takeover detection guide](/guides/ato-detection) * [Deepfake and impersonation detection guide](/guides/deepfake-detection) # Verification packs Source: https://docs.truthlocks.com/guides/verification-packs Use pre-built verification pack templates for common compliance and identity workflows. Verification packs are reusable collections of verification requirements that you can apply to attestation workflows. Truthlocks provides 26 enterprise-grade templates across seven categories, and you can create custom packs for your own use cases. ## When to use verification packs Use verification packs when you need to standardize what gets verified across your organization. For example, if you onboard suppliers and always need to verify their business identity, insurance coverage, and ESG compliance, you can group those requirements into a single pack. ## Available templates Templates are seeded automatically for each tenant. They cover seven categories: ### Identity | Template | Region | | - | - | | KYC Identity Verification | Global | | KYB Business Verification | Global | | Employee Identity & Background | Global | | Digital Identity Binding | Global | ### Compliance | Template | Region | | - | - | | SOC 2 Type II Compliance | Global | | GDPR Data Processing | EU | | ISO 27001 Certification | Global | | Government Contractor (FAR/DFARS) | US | | AML/CFT Compliance | Global | | HIPAA Compliance Attestation | US | ### Financial | Template | Region | | - | - | | Accredited Investor Verification | US | | Bank Account Verification | Global | | Credit Assessment Pack | Global | | Insurance Proof & Coverage | Global | ### Healthcare | Template | Region | | - | - | | Medical License Verification | US | | Clinical Trial Eligibility | Global | | Pharmacy Credential Pack | US | ### Education | Template | Region | | - | - | | Academic Credential Verification | Global | | Professional Certification | Global | | Micro-Credential & Skills Badge | Global | ### Supply chain | Template | Region | | - | - | | Product Authenticity & Provenance | Global | | Supplier Due Diligence | Global | | ESG & Sustainability Attestation | Global | ### Other | Template | Region | | - | - | | Legal Document Attestation | Global | | Age & Eligibility Verification | Global | | Workforce Certification Pack | Global | ## Using a template List available packs (templates are seeded on first access): ```bash theme={null} curl -X GET https://api.truthlocks.com/v1/verification-packs \ -H "X-API-Key: tl_live_your_api_key" ``` Each pack has a `status` field: `active`, `draft`, or `archived`. Only active packs can be linked to verification workflows. ## Creating a custom pack Create your own verification pack when the built-in templates don't cover your workflow: ```bash theme={null} curl -X POST https://api.truthlocks.com/v1/verification-packs \ -H "X-API-Key: tl_live_your_api_key" \ -H "Content-Type: application/json" \ -d '{ "name": "Vendor Onboarding", "description": "Required verifications for new vendor approval", "category": "Supply Chain" }' ``` Custom packs start in `draft` status. Activate them when ready: ```bash theme={null} curl -X POST https://api.truthlocks.com/v1/verification-packs//status \ -H "X-API-Key: tl_live_your_api_key" \ -H "Content-Type: application/json" \ -d '{ "status": "active" }' ``` ## Pack lifecycle | Transition | Effect | | - | - | | `draft` → `active` | Pack can be linked to verification workflows | | `active` → `archived` | Existing links preserved, no new links allowed | | `archived` → `active` | Pack can be linked again | ## Related * [Verification packs API](/api-reference/verification-packs/list) — Full API reference for managing packs. * [Enterprise packs overview](/packs/enterprise/overview) — Enterprise deployment patterns. # Webhooks Source: https://docs.truthlocks.com/guides/webhooks Receive real-time HTTP notifications when events occur in your Truthlocks tenant. Webhooks let your application receive automatic notifications when events happen in your Truthlocks account — for example, when an attestation is minted, a key is rotated, or a verification fails. Instead of polling the API for changes, your server receives an HTTP POST request with the event details. ## How it works **1. Register an endpoint** Add a webhook endpoint in **Settings > Webhooks** in the [tenant console](https://console.truthlocks.com). Provide a publicly reachable HTTPS URL and choose which event types you want to receive. **2. Receive events** When a matching event occurs, Truthlocks sends an HTTP POST request to your URL with a JSON payload describing the event. **3. Verify the signature** Each request includes an HMAC-SHA256 signature in the `X-Truthlocks-Signature` header. Verify it using the endpoint secret to confirm the request came from Truthlocks. **4. Respond with 200** Return an HTTP `200` status code to acknowledge receipt. If your endpoint fails or times out, Truthlocks retries with exponential backoff. ## Event types Events are grouped into categories. You can subscribe to individual events or use a wildcard (`attestation.*`) to receive all events in a category. | Category | Event | Trigger | | :- | :- | :- | | **Attestations** | `attestation.created` | A new attestation is minted | | | `attestation.revoked` | An attestation is revoked | | | `attestation.expired` | An attestation reaches its expiry date | | | `attestation.superseded` | An attestation is replaced by a newer version | | **Verification** | `verification.completed` | A verification check succeeds | | | `verification.failed` | A verification check fails | | **Issuers** | `issuer.created` | A new issuer is registered | | | `issuer.updated` | An issuer's profile or settings change | | | `issuer.suspended` | An issuer is suspended | | **Keys** | `key.created` | A signing key is registered | | | `key.rotated` | A signing key is rotated | | | `key.revoked` | A signing key is revoked | | | `key.compromised` | A key is reported as compromised | | **Team** | `team.member_invited` | A team invitation is sent | | | `team.member_joined` | A team member accepts an invitation | | | `team.member_removed` | A team member is removed | | | `team.role_changed` | A team member's role is updated | | **Billing** | `billing.subscription.created` | A new subscription is created | | | `billing.subscription.updated` | A subscription is modified | | | `billing.invoice.created` | A new invoice is generated | | | `billing.usage.threshold` | A usage threshold is reached | | **Consumer** | `consumer.content.protected` | A consumer protects new content | | **Risk signals** | `risk.signal.created` | A risk signal is ingested (any detection path) | | | `risk.signal.escalated` | A risk signal score crosses the automatic review threshold | | **Receipts** | `receipt.created` | A new receipt is minted | | | `receipt.revoked` | A receipt is revoked | | | `receipt.type.created` | A new receipt type is created | | | `receipt.type.deprecated` | A receipt type is deprecated | | **Security** | `security.password_changed` | A user changes their password | | | `security.api_key_compromised` | An API key is flagged as compromised | | | `security.suspicious_activity` | Suspicious account activity is detected | ### Wildcard filters Use `category.*` to subscribe to every event in a category. For example, `attestation.*` matches `attestation.created`, `attestation.revoked`, `attestation.expired`, and `attestation.superseded`. ## Endpoint limits by plan The number of webhook endpoints you can create depends on your plan tier: | Plan | Endpoint limit | | :- | :- | | Free | 1 | | Starter | 3 | | Business | 10 | | Enterprise | 25 | Need more endpoints? Contact your account manager or upgrade your plan in **Settings > Billing**. ## Creating an endpoint 1. In the tenant console, go to **Settings > Webhooks**. 2. Click **Add endpoint**. 3. Enter a name, your HTTPS destination URL, and select the event types you want to receive. 4. Click **Create**. The console displays your endpoint secret once. Copy it immediately — you cannot retrieve it later. ### Via the API ```http Request theme={null} POST /v1/webhooks/endpoints X-API-Key: tl_live_... Content-Type: application/json { "name": "My Backend", "url": "https://api.example.com/webhooks/truthlock", "event_filters": ["attestation.*", "verification.completed"] } ``` ```json Response theme={null} { "id": "ep_abc123", "name": "My Backend", "url": "https://api.example.com/webhooks/truthlock", "status": "active", "secret": "whsec_...", "event_filters": ["attestation.*", "verification.completed"], "created_at": "2026-03-25T12:00:00Z" } ``` ### Listing endpoints Retrieve all webhook endpoints for your tenant: ```http Request theme={null} GET /v1/webhooks/endpoints X-API-Key: tl_live_... ``` See the full [API reference](/api-reference/webhooks/list-endpoints) for response details. ## Verifying signatures Every webhook request includes a signature header for verification. Always verify signatures before processing events. **Signature format:** ``` X-Truthlocks-Signature: t=1710000000,v1=a1b2c3d4e5f6... ``` Where `t` is the Unix timestamp and `v1` is the HMAC-SHA256 hex digest. **Verification steps:** 1. Extract `t` (timestamp) and `v1` (signature) from the header. 2. Reject the request if the timestamp is more than 5 minutes old. 3. Concatenate `{timestamp}.{raw_request_body}` to form the signing string. 4. Compute HMAC-SHA256 of the signing string using your endpoint secret. 5. Compare the computed digest to `v1` using a constant-time comparison. ```typescript verify-webhook.ts theme={null} import crypto from "crypto"; import express from "express"; const app = express(); app.use(express.raw({ type: "application/json" })); app.post("/webhooks/truthlock", (req, res) => { const sigHeader = req.headers["x-truthlocks-signature"] as string; if (!sigHeader) return res.status(401).send("Missing signature"); const parts = Object.fromEntries( sigHeader.split(",").map((p) => p.split("=") as [string, string]) ); const timestamp = parts["t"]; const signature = parts["v1"]; // Reject stale requests (5-minute window) const age = Math.abs(Date.now() / 1000 - Number(timestamp)); if (age > 300) return res.status(401).send("Timestamp expired"); // Compute expected signature const signingString = `${timestamp}.${req.body.toString()}`; const expected = crypto .createHmac("sha256", process.env.WEBHOOK_SECRET!) .update(signingString) .digest("hex"); // Constant-time comparison if (!crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))) { return res.status(401).send("Invalid signature"); } const event = JSON.parse(req.body.toString()); console.log("Received event:", event.type); res.status(200).json({ received: true }); }); ``` ```go verify-webhook.go theme={null} package main import ( "crypto/hmac" "crypto/sha256" "encoding/hex" "fmt" "io" "math" "net/http" "strconv" "strings" "time" ) func verifyWebhook(r *http.Request, secret string) ([]byte, error) { sig := r.Header.Get("X-Truthlocks-Signature") if sig == "" { return nil, fmt.Errorf("missing signature header") } parts := map[string]string{} for _, p := range strings.Split(sig, ",") { kv := strings.SplitN(p, "=", 2) if len(kv) == 2 { parts[kv[0]] = kv[1] } } ts, _ := strconv.ParseInt(parts["t"], 10, 64) age := math.Abs(float64(time.Now().Unix() - ts)) if age > 300 { return nil, fmt.Errorf("timestamp expired") } body, err := io.ReadAll(r.Body) if err != nil { return nil, err } mac := hmac.New(sha256.New, []byte(secret)) mac.Write([]byte(fmt.Sprintf("%d.%s", ts, body))) expected := hex.EncodeToString(mac.Sum(nil)) if !hmac.Equal([]byte(parts["v1"]), []byte(expected)) { return nil, fmt.Errorf("invalid signature") } return body, nil } ``` ```python verify_webhook.py theme={null} import hashlib import hmac import time from flask import Flask, request, abort app = Flask(__name__) @app.route("/webhooks/truthlock", methods=["POST"]) def handle_webhook(): sig_header = request.headers.get("X-Truthlocks-Signature", "") parts = dict(p.split("=", 1) for p in sig_header.split(",")) timestamp = parts.get("t", "") signature = parts.get("v1", "") # Reject stale requests if abs(time.time() - int(timestamp)) > 300: abort(401, "Timestamp expired") # Compute expected signature signing_string = f"{timestamp}.{request.get_data(as_text=True)}" expected = hmac.new( WEBHOOK_SECRET.encode(), signing_string.encode(), hashlib.sha256, ).hexdigest() if not hmac.compare_digest(signature, expected): abort(401, "Invalid signature") event = request.get_json() print(f"Received event: {event['type']}") return {"received": True} ``` > [!WARNING] > > Always use a constant-time comparison function (like `crypto.timingSafeEqual` or `hmac.compare_digest`) to prevent timing attacks. ## Request headers Every webhook delivery includes these headers: | Header | Description | | :- | :- | | `Content-Type` | `application/json` | | `User-Agent` | `Truthlocks-Webhook-Service/1.0` | | `X-Truthlocks-Event-Id` | Unique identifier for the event | | `X-Truthlocks-Event-Type` | Event type (e.g., `attestation.created`) | | `X-Truthlocks-Timestamp` | Unix timestamp of the delivery attempt | | `X-Truthlocks-Signature` | HMAC-SHA256 signature for verification | ## Retry behavior If your endpoint returns a non-2xx status code or doesn't respond within 5 seconds, Truthlocks retries the delivery with exponential backoff: | Attempt | Approximate delay | | :- | :- | | 1st retry | \~1 second | | 2nd retry | \~2 seconds | | 3rd retry | \~4 seconds | | 4th retry | \~16 seconds | | 5th retry | \~1 minute | | 6th retry | \~2 minutes | | 7th retry | \~5 minutes (max) | Delays include up to 30% jitter. After 8 total attempts (1 initial + 7 retries), the delivery is marked as failed. You can view delivery attempts and failure details in **Settings > Webhooks** by clicking on an endpoint, or query them via the API: ```http Request theme={null} GET /v1/webhooks/endpoints/{id}/deliveries X-API-Key: tl_live_... ``` See the [list deliveries API reference](/api-reference/webhooks/list-deliveries) for response details. ## Rotating secrets If your webhook secret is compromised, rotate it immediately: 1. In the tenant console, go to **Settings > Webhooks** and click on the endpoint. 2. Click **Rotate secret**. 3. Copy the new secret — the old secret stops working immediately. You can also rotate via the API: ```http Request theme={null} POST /v1/webhooks/endpoints/{id}/rotate X-API-Key: tl_live_... ``` ## Testing webhooks Send a test event to verify your endpoint is working: 1. In the tenant console, go to **Settings > Webhooks** and click on the endpoint. 2. Click **Send test**. 3. A `webhook.test` event is sent to your URL using the full signing and delivery pipeline. Via the API: ```http Request theme={null} POST /v1/webhooks/test-delivery X-API-Key: tl_live_... Content-Type: application/json { "endpoint_id": "ep_abc123", "event_type": "webhook.test", "payload": { "status": "ok", "source": "test-delivery" } } ``` The `event_type` and `payload` fields are optional — they default to `webhook.test` and a basic status payload if omitted. ## Risk signal notifications You can receive real-time webhook notifications whenever a risk signal is created by any of the five [Anti-Fraud Identity Firewall](/guides/risk-signals) detection paths — direct ingestion, event normalization, deepfake scanning, ATO detection, and velocity scoring. Subscribe to `risk.signal.*` to receive all risk signal events, or subscribe to `risk.signal.created` or `risk.signal.escalated` individually. ### Example payload ```json theme={null} { "id": "evt_r1s2k3...", "type": "risk.signal.created", "created_at": "2027-07-24T09:15:00Z", "data": { "signal_id": "a1b2c3d4-...", "signal_source": "velocity", "signal_type": "velocity", "risk_score": 72, "subject_type": "user", "subject_id": "usr_8f14e45f" } } ``` ### Responding to risk signals Use risk signal webhooks to trigger automated responses — block a user session, notify your security team, or escalate to a fraud case — without polling the API. ```javascript theme={null} app.post("/webhooks/truthlock", (req, res) => { const event = JSON.parse(req.body.toString()); if (event.type === "risk.signal.created") { const { risk_score, subject_id, signal_type } = event.data; if (risk_score >= 80) { // Critical — block immediately and alert security blockSubject(subject_id); notifySecurityTeam(event.data); } else if (risk_score >= 60) { // High — throttle and log for review throttleSubject(subject_id); } } res.status(200).json({ received: true }); }); ``` > [!NOTE] > > Risk signal webhooks fire for signals created by all five detection paths. The `signal_source` field in the payload tells you which path generated the signal — `external`, `event_normalization`, `deepfake`, `ato`, or `velocity`. ## Best practices > [!TIP] > > Respond to webhooks quickly. Do your heavy processing asynchronously after returning a `200` response to avoid timeouts and retries. * **Verify every signature.** Never skip signature verification, even in development. * **Use a message queue.** Enqueue incoming events and process them in a worker to avoid blocking the HTTP response. * **Handle duplicates.** Use the `X-Truthlocks-Event-Id` header to deduplicate events in case of retries. * **Monitor delivery failures.** Check the deliveries tab in the console regularly for failed or dead deliveries. * **Keep secrets secure.** Store your webhook secret in environment variables, not in source code. # Introduction Source: https://docs.truthlocks.com/introduction Enterprise-grade attestation infrastructure for digital credentials. # Welcome to Truthlocks Enterprise-grade attestation infrastructure for issuing, managing, and verifying cryptographically signed digital credentials at scale. ## What is Truthlocks? Truthlocks is a cloud-native platform that enables organizations to issue tamper-evident digital attestations. Whether you're issuing academic credentials, professional certifications, identity verification tokens, or compliance attestations, Truthlocks provides the cryptographic infrastructure to make claims verifiable anywhere, by anyone. > **Cryptographic Integrity** > > Attestations use a supported signing algorithm and transparency evidence. > Verification can detect changes to the signed payload; it does not prove that its claims are true. > **Trust Registry** > > Issuer records identify the source of a claim. Staff-reviewed identity evidence > and production onboarding are separate from creating an issuer; inspect the > published trust state and verification evidence. > **Real-time Verification** > > Verify any attestation in milliseconds with a single API call. Get > cryptographic proof of validity, revocation status, and issuer trust level. > **Enterprise Security** > > Workspace access controls, MFA, organization SSO and recorded audit evidence > support security reviews. These features do not constitute a SOC 2 report or > ISO/IEC 27001 certification. ## Two ways to use Truthlocks Truthlocks serves both organizations issuing credentials at scale and individual creators proving authorship of their work. ### For organizations (B2B) Register an issuer, manage signing keys, and mint attestations for credentials like diplomas, certifications, and compliance records. Verifiers can check any attestation with a single API call. ### For individual creators (B2C) Protect your original content — photos, code, designs, documents — with a single API call. Hash your file client-side, submit the hash, and receive a shareable proof URL. Your signing identity is provisioned automatically on first use. The [consumer mint endpoint](/api-reference/consumer/mint) returns `content_hash`, `protected_at`, and a `verify_url` in the response, so you can confirm exactly what was protected and share the proof immediately without a follow-up call. Anyone can view the proof page or fetch its metadata via the public [proof metadata endpoint](/api-reference/consumer/proof-metadata) — no authentication required. > **[B2B quickstart](/quickstart)** > > Issue your first enterprise attestation in under 5 minutes. > **[Content protection guide](/guides/content-protection)** > > Protect your first file and share a proof link. ## Use cases Truthlocks is designed for any scenario where you need to issue verifiable claims that third parties can trust without contacting the issuer directly. ### Content protection * **Creative work:** Prove authorship of photos, designs, music, and video with timestamped cryptographic proofs * **Source code:** Establish provenance for code files and repositories * **AI-generated content:** Record provenance metadata for AI outputs ### Education & credentials * **Academic degrees:** Issue transcripts and diplomas that employers can verify instantly * **Professional certifications:** AWS, Google Cloud, CFA — all verifiable on-demand * **Continuing education:** Track and verify CPE credits for licensed professionals ### Identity & access * **Age verification:** Prove users are 18+ without revealing exact birthdate * **Employment verification:** Confirm current employment status for background checks * **KYC/AML attestations:** Share verification status across platforms ### Machine identity The [Machine Agent Identity Protocol (MAIP)](/guides/machine-identity) is generally available. MAIP gives your AI agents, pipelines, and automated systems a verifiable identity with cryptographic receipts, trust scoring, and a full audit trail. * **Agent registry:** Register AI agents with unique identifiers and Ed25519 keypairs. Manage the full lifecycle — create, update, suspend, and revoke — via the [agents API](/api-reference/machine-identity/agents/register) * **Session-based authorization:** Create short-lived, scope-bound sessions with automatic expiry and least-privilege tool access controls. See [agent authorization](/guides/agent-authorization) * **Trust scores:** Compute continuous 0–100 trust scores based on receipt history, compliance status, and peer attestations. See [trust scores](/guides/trust-scores) * **AI orchestration:** Coordinate multi-agent tasks using sequential, parallel, hierarchical, or competitive execution patterns with built-in cost tracking and safety guardrails. See [AI orchestration](/guides/ai-orchestration) * **Cross-tenant delegation:** Offer and accept bilateral trust delegations between tenants with configurable depth limits and receipt chains. See [cross-tenant delegation](/guides/cross-tenant-delegation) * **Integrations:** Integrations for Slack, GitHub Action, Linear, Notion, VS Code, JetBrains, Neovim, MCP Server, multi-backend event streaming, and AI model connectors for LangChain, LlamaIndex, CrewAI, and more. Browse all available connectors on the [Integrations Hub](https://truthlocks.com/resources/integrations) or see the [MAIP integrations guide](/guides/maip-integrations) ### Anti-fraud & risk The [Anti-Fraud Identity Firewall](/guides/risk-signals) is generally available. It provides a centralized pipeline for ingesting, normalizing, and querying fraud-detection signals across your identity infrastructure, with real-time [webhook notifications](/guides/webhooks) for all signal types. * **Risk signal ingestion:** Feed fraud-detection signals from any source — device fingerprinting, IP reputation, email verification, or your own rules — via [`POST /v1/risk/signals`](/api-reference/risk/ingest-signal). Supports idempotent retries and six entity types (`user`, `issuer`, `session`, `device`, `ip`, `attestation`). * **Event normalization:** Submit raw identity events (failed logins, invalid signatures, deepfake suspects) via [`POST /v1/risk/events`](/api-reference/risk/normalize-event) and have them automatically mapped to risk signals with pre-calibrated scores * **Risk & Fraud console:** Browse, filter, and inspect all ingested signals with color-coded score badges in the **Risk & Fraud > Signals** console page * **Deepfake and impersonation detection:** Scan images, videos, documents, and attestations for manipulation indicators via [`POST /v1/risk/deepfake/scan`](/api-reference/risk/deepfake-scan). Scans that exceed the risk threshold automatically create a risk signal. See the [deepfake detection guide](/guides/deepfake-detection) * **Account takeover detection:** Monitor login velocity per subject and automatically flag account takeover attempts via [`POST /v1/risk/ato/evaluate`](/api-reference/risk/ato-evaluate). The platform tracks failed logins in a rolling one-hour window and creates alerts and risk signals when thresholds are crossed. See the [ATO detection guide](/guides/ato-detection) * **Velocity and anomaly scoring:** Track action frequency across rolling time windows (1 m, 5 m, 1 h, 24 h) via [`POST /v1/risk/velocity/record`](/api-reference/risk/velocity-record). The platform computes a weighted velocity score biased toward burst detection and auto-ingests risk signals when the score reaches 60 or above. See the [velocity scoring guide](/guides/velocity-scoring) * **Device fingerprinting:** Track device-level fraud indicators like emulators and spoofed attributes * **IP reputation scoring:** Flag VPNs, proxies, and datacenter IPs with risk scores * **Behavioral analysis:** Detect velocity anomalies and suspicious session patterns ### Compliance & governance * **Regulatory compliance:** Prove compliance with GDPR, HIPAA, SOX * **Supply chain:** Attest to origin, handling, and quality of goods * **Financial services:** Issue and verify trade confirmations and settlements ## Architecture Overview Truthlocks is built as a set of microservices deployed on AWS ECS Fargate, designed for horizontal scalability and high availability. ```text theme={null} ┌─────────────────────────────────────────────────────────────┐ │ API Gateway │ │ (Rate Limiting, Auth, Routing) │ └─────────────────────────────────────────────────────────────┘ │ ┌─────────────────────┼─────────────────────┐ ▼ ▼ ▼ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ Attestation │ │ Trust │ │ Governance │ │ Service │ │ Registry │ │ Service │ └──────────────┘ └──────────────┘ └──────────────┘ │ │ │ └─────────────────────┼─────────────────────┘ ▼ ┌──────────────────┐ │ Signing Service │ │ (Ed25519 Keys) │ └──────────────────┘ │ ▼ ┌──────────────────┐ │ Transparency Log │ │ (Append-only) │ └──────────────────┘ ``` ## Getting started Choose the path that matches your use case: **Individual creators** **1. Sign up** Create an account at [verify.truthlocks.com](https://verify.truthlocks.com). **2. Protect content** Upload a file on the Protect page or call the [consumer mint API](/api-reference/consumer/mint). Your signing identity is created automatically. **3. Share your proof** Use the `verify_url` from the response to share a public proof page that anyone can view without logging in. **Organizations** **1. Create an account** Sign up at [console.truthlocks.com](https://console.truthlocks.com) to get your tenant and API credentials. **2. Register an issuer** Create an issuer profile with your organization details and register your Ed25519 signing key. **3. Mint your first attestation** Use the SDK or REST API to create cryptographically signed attestations for your users or entities. **4. Verify anywhere** Share the attestation ID with anyone. They can verify authenticity instantly using the public verification endpoint. ## Next Steps > **[Quick Start](/quickstart)** > > Issue your first attestation in under 5 minutes with our step-by-step guide. > **[Core Concepts](/concepts)** > > Understand tenants, issuers, attestations, and the verification model. > **[API Reference](/api-reference/attestations/mint)** > > Explore documented operations with an interactive playground — build requests, switch environments, and send them from the docs. # Error Codes Reference Source: https://docs.truthlocks.com/ops/errors Canonical error codes and verdicts used across the Truthlocks platform. These codes are stable and can be used for programmatic error handling. Canonical error codes and verdicts used across the Truthlocks platform. These codes are stable and can be used for programmatic error handling. ## Verification Verdicts | Verdict | CLI Exit | Description | | - | - | - | | VALID | 0 | Attestation verified successfully | | ALTERED | 10 | Payload hash does not match | | REVOKED | 11 | Attestation has been revoked | | KEY\_COMPROMISED | 12 | Signing key marked as compromised | | KEY\_EXPIRED | 13 | Signing key has expired | | LOG\_PROOF\_FAILED | 14 | Transparency log proof verification failed | | SIGNATURE\_INVALID | 15 | Cryptographic signature verification failed | ### Verification reasons When you call the [Verify endpoint](/api-reference/verify), the response includes a `reasons` array with additional context. These reason codes are informational and appear alongside the verdict: | Reason | Verdict | Description | | :- | :- | :- | | `document_hash_mismatch` | `ALTERED` | The `document_hash_hex` you provided does not match the hash stored at mint time | | `document_hash_not_stored` | (any) | The attestation was minted without a document hash, so the document hash check was skipped | ## API error codes ### General | Code | HTTP | Description | | :- | :- | :- | | `INVALID_INPUT` | 400 | Request validation failed | | `INVALID_REQUEST` | 400 | Request body or parameters are malformed | | `INVALID_ID` | 400 | Identifier is not a valid UUID | | `NOT_FOUND` | 404 | Resource not found | | `UNAUTHORIZED` | 401 | Authentication required | | `FORBIDDEN` | 403 | Permission denied | | `CONFLICT` | 409 | Resource state conflict | | `INTERNAL_ERROR` | 500 | An unexpected server error occurred | | `DB_ERROR` | 500 | A database operation failed | ### Attestations and issuers | Code | HTTP | Description | | :- | :- | :- | | `ISSUER_NOT_TRUSTED` | 403 | Issuer must be in `trusted` status to mint attestations | | `KEY_INACTIVE` | 400 | Signing key is not active | ### API keys | Code | HTTP | Description | | :- | :- | :- | | `NAME_REQUIRED` | 400 | A key name is required | | `KEY_ID_REQUIRED` | 400 | Key ID parameter is missing | | `KEY_NOT_FOUND` | 404 | API key not found | | `KEY_LIMIT` | 409 | Maximum number of active API keys reached (5 per consumer) | ### Consumer | Code | HTTP | Description | | :- | :- | :- | | `CONSUMER_REQUIRED` | 400 | A consumer email reference is required | ### Identity and DID | Code | HTTP | Description | | :- | :- | :- | | `MISSING_DID` | 400 | DID parameter is required | | `DID_NOT_FOUND` | 404 | DID not found or the associated issuer has been revoked | | `MISSING_ID` | 400 | Issuer ID parameter is required | | `EMAIL_NOT_VERIFIED` | 403 | Email address has not been verified | ### SSO | Code | HTTP | Description | | :- | :- | :- | | `DISCOVERY_FAILED` | 400 | OIDC discovery configuration could not be loaded | | `METADATA_FETCH_FAILED` | 400 | SAML IdP metadata could not be fetched | | `CRYPTO_ERROR` | 500 | An encryption operation failed | | `TEST_FAILED` | 400 | SSO connection test did not succeed | | `AUTH_FAILED` | 401 | SSO authentication failed | | `INVALID_STATE` | 401 | OAuth or SAML state parameter is invalid | | `EXPIRED_SESSION` | 401 | SSO login session has expired | | `REPLAY_DETECTED` | 401 | OAuth or SAML state token has already been used | | `CONFIG_ERROR` | 500 | SSO configuration is missing or invalid | ### Policy and governance | Code | HTTP | Description | | :- | :- | :- | | `POLICY_VIOLATION` | 403 | Request violates an active policy | ### Billing and limits | Code | HTTP | Description | | :- | :- | :- | | `BILLING_LIMIT` | 402 | Billing quota exhausted for the current cycle | | `LIMIT_REACHED` | 429 | Monthly protection limit reached | | `SEAT_LIMIT` | 402 | Team seat limit reached — upgrade your plan or remove an existing member | ### Data residency | Code | HTTP | Description | | :- | :- | :- | | `REGION_MISMATCH` | 409 | Tenant is pinned to a different region than the one processing the request | ## Retryable vs. terminal errors When deciding whether to retry a failed request, use the HTTP status code to determine if the error is transient or permanent. ### Retryable (transient) These errors are automatically retried by the [SDKs](/sdk/go) when `MaxRetries` (or equivalent) is configured: | HTTP status | Code | When to retry | | :- | :- | :- | | `408` | Request Timeout | Immediately — the server did not receive the request in time | | `429` | `RATE_LIMITED` | After the duration specified in the `Retry-After` header | | `500` | `INTERNAL_ERROR` | With exponential backoff — transient server issue | | `502` | Bad Gateway | With exponential backoff — upstream service unavailable | | `503` | Service Unavailable | With exponential backoff — service temporarily overloaded | | `504` | Gateway Timeout | With exponential backoff — upstream service timed out | ### Terminal (do not retry) These errors indicate a problem with the request that won't resolve by retrying: | HTTP status | Example codes | Action | | :- | :- | :- | | `400` | `INVALID_INPUT`, `INVALID_REQUEST` | Fix the request payload | | `401` | `UNAUTHORIZED` | Check your API key or authentication token | | `403` | `FORBIDDEN`, `ISSUER_NOT_TRUSTED`, `POLICY_VIOLATION` | Check permissions or issuer status | | `404` | `NOT_FOUND` | Verify the resource ID exists | | `409` | `CONFLICT` | Resolve the state conflict before retrying | > [!TIP] > > All three SDKs handle retryable errors automatically with exponential backoff and jitter. You only need manual retry logic if you've disabled automatic retries or want custom behavior on top of the SDK defaults. ## Error response format Every error response returns a JSON object with two fields: ```json theme={null} { "code": "ISSUER_NOT_TRUSTED", "message": "Issuer must be in trusted status to mint attestations" } ``` * **`code`** — a stable, machine-readable error code from the tables above. Use this for programmatic error handling. * **`message`** — a human-readable description of what went wrong. Messages may change between releases; do not match on them programmatically. > [!NOTE] > > Error messages that would expose infrastructure details (such as database connection strings or internal hostnames) are automatically replaced with a generic message before being returned to the client. The original details are logged server-side only. ## Gateway errors (RFC 7807) When a request reaches the API gateway but does not match any valid route, the gateway returns a structured error response following the [RFC 7807 Problem Details](https://www.rfc-editor.org/rfc/rfc7807) specification. This applies to `404 Not Found` and `405 Method Not Allowed` errors at the gateway level. ### Response format Gateway errors use `application/problem+json` as the content type and include four fields: ```json theme={null} { "type": "https://docs.truthlocks.com/ops/errors", "title": "Not Found", "status": 404, "detail": "The requested path does not match any API route." } ``` | Field | Description | | :- | :- | | `type` | A URI reference that identifies the error type. Points to this documentation page. | | `title` | A short summary of the error. Either `Not Found` or `Method Not Allowed`. | | `status` | The HTTP status code — `404` or `405`. | | `detail` | A human-readable explanation of the specific error. | ### When you see these errors * **`404 Not Found`** — The request path does not match any API route. Double-check the URL, including the `/v1/` version prefix and resource name. * **`405 Method Not Allowed`** — The request path exists, but the HTTP method you used (for example, `DELETE` on a read-only endpoint) is not supported. Check the [API reference](/api-reference/attestations/mint) for the correct method. ### Handling gateway errors in code If you parse error responses programmatically, check the `Content-Type` header to distinguish gateway errors from application errors: * **`application/problem+json`** — Gateway-level error (RFC 7807). Use the `status` and `title` fields. * **`application/json`** — Application-level error. Use the `code` and `message` fields. ```javascript theme={null} const res = await fetch("https://api.truthlocks.com/v1/nonexistent"); const contentType = res.headers.get("content-type"); if (contentType?.includes("application/problem+json")) { // Gateway error — RFC 7807 format const problem = await res.json(); console.error(`${problem.status} ${problem.title}: ${problem.detail}`); } else { // Application error — standard format const error = await res.json(); console.error(`${error.code}: ${error.message}`); } ``` > [!TIP] > > The Truthlocks [SDKs](/sdk/js) handle both error formats automatically. You only need to distinguish between them if you are calling the API directly. ## Canonical Enums > **Algorithm** > > \* `Ed25519` \* `ES256` \* `ES384` \* `ES512` \* `RS256` \* `RS384` \* `RS512` \* `PS256` \* `PS384` \* `PS512` > **Issuer Status** > > * `pending` \* `trusted` \* `suspended` \* `revoked` > **Trust Tier** > > * `self_issued` \* `verified_org` \* `regulated_issuer` > **Key Status** > > * `ACTIVE` \* `DISABLED` \* `EXPIRED` \* `COMPROMISED` > **Attestation Status** > > \* `ACTIVE` \* `REVOKED` \* `SUPERSEDED` > **Risk Rating** > > * `unknown` \* `low` \* `medium` \* `high` \* `critical` # Health & Readiness Source: https://docs.truthlocks.com/ops/health Monitoring API health, readiness endpoints, and status page. Monitor Truthlocks API health, check readiness for dependencies, and integrate with your observability stack. ## Health Endpoints ### Liveness Probe Check if the API is running. Use for Kubernetes liveness probes: ```http theme={null} GET https://api.truthlocks.com/health/live # Response (200 OK) { "status": "ok", "timestamp": "2026-01-13T12:00:00Z" } ``` ### Readiness Probe Check if the API is ready to serve traffic (all dependencies healthy): ```http theme={null} GET https://api.truthlocks.com/health/ready # Response (200 OK - All systems operational) { "status": "ok", "timestamp": "2026-01-13T12:00:00Z", "checks": { "database": "ok", "redis": "ok", "signing_service": "ok", "transparency_log": "ok" } } ``` ```http theme={null} # Response (503 Service Unavailable - Degraded) { "status": "degraded", "timestamp": "2026-01-13T12:00:00Z", "checks": { "database": "ok", "redis": "timeout", "signing_service": "ok", "transparency_log": "ok" } } ``` ## Kubernetes Configuration If you're building applications that depend on Truthlocks, configure your probes to check both your app and the Truthlocks API: ```yaml theme={null} apiVersion: v1 kind: Deployment metadata: name: my-app spec: template: spec: containers: - name: app livenessProbe: httpGet: path: /health/live port: 8080 initialDelaySeconds: 5 periodSeconds: 10 readinessProbe: httpGet: path: /health/ready port: 8080 initialDelaySeconds: 10 periodSeconds: 5 failureThreshold: 3 ``` ### Example Readiness Check (App) ```javascript theme={null} // Include Truthlocks health in your app's readiness app.get('/health/ready', async (req, res) => { const checks = { database: await checkDatabase(), truthlock: await checkTruthlock(), }; const allHealthy = Object.values(checks).every(c => c === 'ok'); res.status(allHealthy ? 200 : 503).json({ status: allHealthy ? 'ok' : 'degraded', checks, }); }); async function checkTruthlock(): Promise { try { const res = await fetch('https://api.truthlocks.com/health/ready', { timeout: 5000, }); return res.ok ? 'ok' : 'degraded'; } catch { return 'unreachable'; } } ``` ## Status page Check real-time service health and uptime at [status.truthlocks.com](https://status.truthlocks.com). The status page auto-refreshes every 60 seconds and requires no authentication. ### Monitored services The status page tracks health for each core service independently: | Service | Description | | - | - | | API Gateway | Main API endpoint for all requests | | Trust Registry | Issuer management and governance | | Billing | Subscription and payment processing | | Signing | Cryptographic signing operations | | Attestations | Attestation minting and management | | Audit Logs | Activity logging and compliance | | Transparency Log | Cryptographic append-only log | | Verification | Proof bundle verification | | Machine Identity | Agent registration, sessions, and trust scoring | | AI CMO | AI content moderation and orchestration | Each service reports one of four statuses: **operational**, **degraded**, **outage**, or **unknown**. The page displays a per-service response time and an overall system health banner. ### Uptime history A 90-day uptime bar shows daily availability for each service. Hover over any day to see the date and uptime percentage. An overall uptime percentage is displayed alongside each service. ### Incident history Visit the **Incident History** page to see past incidents in a timeline format. Each entry includes the severity level, affected services, and timestamped updates from investigation through resolution. ### Subscribe to notifications Enter your email at the bottom of the status page to receive incident notifications. You will be notified when incidents are created, updated, or resolved. Enterprise customers can also configure webhook callbacks to receive status change events automatically. ### Programmatic status API Query the status API for machine-readable service health. Use this to integrate Truthlocks availability into your own dashboards, alerting pipelines, or pre-flight checks. No authentication is required. ```http theme={null} GET https://status.truthlocks.com/api/health ``` The endpoint returns the overall system status, a timestamp, and an array of per-service health checks: ```json theme={null} { "status": "operational", "timestamp": "2026-03-26T14:30:00Z", "services": [ { "id": "api-gateway", "name": "API Gateway", "status": "operational", "responseTime": 42 }, { "id": "signing-service", "name": "Signing", "status": "degraded", "responseTime": 1200, "error": "HTTP 503" } ] } ``` **Response fields:** | Field | Type | Description | | - | - | - | | `status` | string | Overall system health: `operational`, `degraded`, or `outage`. | | `timestamp` | string | ISO 8601 timestamp of the check. | | `services` | array | Per-service health results. | | `services[].id` | string | Machine-readable service identifier (e.g., `api-gateway`, `signing-service`). | | `services[].name` | string | Human-readable service name. | | `services[].status` | string | Service health: `operational`, `degraded`, or `outage`. | | `services[].responseTime` | number or null | Response time in milliseconds, or `null` if unreachable. | | `services[].error` | string | Present only when the service is not operational. | The overall status is `outage` if any service is down, `degraded` if any service is slow or returning errors, and `operational` when all services are healthy. **Example: poll status from your app** ```javascript theme={null} async function checkTruthlockStatus() { const res = await fetch("https://status.truthlocks.com/api/health"); const data = await res.json(); if (data.status !== "operational") { console.warn(`Truthlocks is ${data.status}`); const issues = data.services.filter((s) => s.status !== "operational"); issues.forEach((s) => console.warn(` ${s.name}: ${s.status} — ${s.error}`)); } return data; } ``` **Example: pre-flight check before minting** Check that the signing and attestation services are healthy before attempting a mint operation. This avoids unnecessary retries when you already know the required services are down. ```javascript theme={null} async function mintWithStatusCheck(attestation) { const status = await fetch("https://status.truthlocks.com/api/health"); const health = await status.json(); const signing = health.services.find((s) => s.id === "signing-service"); const attestations = health.services.find( (s) => s.id === "attestation-service" ); if ( signing?.status !== "operational" || attestations?.status !== "operational" ) { throw new Error("Required services are not operational — retry later"); } return client.attestations.mint(attestation); } ``` > [!NOTE] > > The status API is rate-limited to prevent abuse. For continuous monitoring, > poll no more frequently than once every 30 seconds. For the full response schema, monitored service IDs, and additional examples, see the [status API reference](/api-reference/health/status). > **[Status page](https://status.truthlocks.com)** > > Real-time service health and incident history. > **Webhook notifications** > > Enterprise customers can configure webhook callbacks for status changes. > **[Status API reference](/api-reference/health/status)** > > Full API reference for the programmatic status endpoint. > **Email alerts** > > Subscribe on the status page for incident notifications. ## Service-level commitments Availability targets, support coverage, response times and service credits apply only when explicitly agreed in the applicable contract. Public health checks report observed service state; they do not establish a guaranteed uptime percentage, end-to-end recovery capability or staffed support schedule. Confirm the current deployment and recovery evidence before relying on a commitment. ## Monitoring Integration Integrate Truthlocks health checks with your observability tools: ```yaml Prometheus theme={null} # prometheus.yml scrape_configs: - job_name: "truthlock-health" scrape_interval: 30s metrics_path: /metrics static_configs: - targets: ["api.truthlocks.com"] ``` ```yaml Datadog theme={null} # datadog.yaml init_config: instances: - name: truthlock_api url: https://api.truthlocks.com/health/ready timeout: 5 content_match: '"status":"ok"' http_response_status_code: 200 tags: - service:truthlock - env:production ``` ```javascript Custom Dashboard Metrics theme={null} // Export key metrics for dashboards const metrics = { "truthlock.availability": isHealthy ? 1 : 0, "truthlock.latency_ms": responseTime, "truthlock.ratelimit_remaining": rateLimitRemaining, "truthlock.attestations_today": dailyCount, }; ``` ## Gateway resilience The API gateway includes automatic panic recovery and zero-downtime deployment support: * **Panic recovery** — If the gateway encounters an unexpected internal error, it recovers automatically and returns a structured error response instead of dropping your connection. You do not need to handle dropped connections caused by gateway-level panics. * **Graceful shutdown** — During deployments, the gateway and signing service drain in-flight requests over a 15-second window instead of terminating them immediately. If you previously experienced occasional request failures during maintenance windows, those should no longer occur. These protections work automatically and require no changes to your integration. ## Incident response If Truthlocks is experiencing issues: 1. **Check status page:** [status.truthlocks.com](https://status.truthlocks.com) 2. **Enable circuit breaker:** Fail gracefully in your app 3. **Queue operations:** Retry attestation minting later 4. **Contact support:** For Enterprise SLA escalation ### Circuit Breaker Pattern ```javascript theme={null} import CircuitBreaker from "opossum"; const breaker = new CircuitBreaker( async (attestation) => client.attestations.mint(attestation), { timeout: 5000, // Fail if no response in 5s errorThresholdPercentage: 50, // Open if 50% fail resetTimeout: 30000, // Try again after 30s }, ); breaker.fallback(() => { // Queue for retry later queue.add("retry-attestation", attestation); return { queued: true }; }); ``` ## Next steps > **[Observability dashboard](/guides/observability)** > > Monitor service health, latency, and usage from the console. > **[Error reference](/ops/errors)** > > Complete list of error codes and handling. > **[Rate limits](/ops/limits)** > > Handle rate limiting gracefully. # Limits and retries Source: https://docs.truthlocks.com/ops/limits Handle current quotas and transient rate limits without duplicating writes. Limits depend on the workspace plan, operation, environment, and service configuration. Use your current usage and entitlements responses rather than historical tier tables as an integration contract. ## Rate limits and quotas HTTP 429 means a rate limit was applied. It does not always mean a paid upgrade is required. A service may return a separate billing or quota error, such as HTTP 402. Read the status and structured error body. Respect `Retry-After` when present. Not every endpoint emits the same rate-limit headers, and an omitted header does not mean there is no limit. Public verification can also be rate-limited. ## Retry policy Retry reads after transient failures using a bounded backoff and jitter. Retry writes only when the operation supports idempotency and you retain the same request body and idempotency key. Do not blindly retry payment, notification, or provisioning requests. A timeout leaves the outcome uncertain. Query the resulting resource where possible before creating a second operation. Treat authentication errors and invalid requests as problems to correct, not reasons for an immediate retry loop. See [billing usage](/api-reference/billing/usage), [entitlements](/api-reference/billing/entitlements), and the [mint quickstart](/quickstart). # B2B Onboarding Pack Source: https://docs.truthlocks.com/packs/enterprise/b2b-onboarding Strategic Integration Guide for Enterprise Issuers **Strategic Integration Guide for Enterprise Issuers** ## Executive Summary This document outlines the end-to-end journey for private sector organizations adopting Truthlocks to issue, manage, and verify digital attestations. Truthlocks provides a high-integrity "Source of Truth" without the overhead of blockchain, utilizing signed checkpoint transparency and robust tenant isolation. *** ## 1. Architecture Overview Truthlocks is built on the principle of **High-Integrity Provenance**. * **No Blockchain**: Unlike legacy DLT solutions, we focus on high-speed, verifiable transaction logs that are cryptographically signed by both the Issuer and the Platform. * **Signed Checkpoint Transparency**: Every action within a tenant realm is logged and periodically "checkpointed." These checkpoints are public-eligible but payload-private, ensuring transparency without data leakage. * **Proof Bundles**: End-users (consumers) receive self-contained proof bundles that can be verified offline or via the Truthlocks Verify portal. ## 2. Security & Trust Model Our security architecture follows a multi-layered defense strategy: | Layer | Implementation | | :- | :- | | **Identity** | Federated SSO (OIDC/SAML) + Hardware MFA support. | | **Cryptography** | Ed25519 signing keys for issuers; AES-256-GCM for data at rest. | | **Isolation** | Row-Level Security (RLS) ensures absolute separation between tenant data. | | **Key Lifecycle** | Automated rotation schedules and tamper-evident revocation logs. | ## 3. The Onboarding Workflow Issuers move through four distinct phases: 1. **Application**: Submission of organizational evidence to the Platform Admin. 2. **Verification**: Platform review of institutional credentials and signing key ownership. 3. **Tier Assignment**: Allocation of trust tiers (Standard vs. Verified) based on evidence depth. 4. **Activation**: Issuance of API keys and configuration of tenant webhook endpoints. ## 4. Integration Roadmap Engineering teams should follow this sequence for a successful rollout: * **Auth & API Keys**: Issue system-to-system keys via the Tenant Console. * **Webhook Registration**: Subscribe to `attestation.minted` and `issuer.updated` events. * **SDK Setup**: Initialize the Go or JavaScript SDK with your tenant credentials. * **Environment Separation**: Utilize separate `Development` and `Production` realms for CI/CD safety. ## 5. Billing & Entitlements Truthlocks utilizes a "Pay-as-you-grow" model controlled via **Entitlements**: * **Quotas**: Soft and hard limits on attestation volume and concurrent users. * **Features**: Modular access to advanced auditing, multi-region residency, and enterprise SSO. * **African Gateways**: Full support for Flutterwave and Paystack for regional compliance and currency handling. *** ## Appendix: Sample Workflow ```mermaid theme={null} sequenceDiagram participant I as Issuer (B2B) participant T as Truthlocks Platform participant C as Consumer I->>T: Post /v1/attestations/mint T-->>I: 202 Accepted (Queued) T->>T: Log & Sign Checkpoint T->>I: Webhook (attestation.minted) I->>C: Deliver Proof Bundle (Email/App) C->>T: Verify via verify.truthlocks.com ``` > [!NOTE] > > This guide is intended for institutional decision-makers and technical leads. > For API specifics, see the [Technical Integration > Pack](/packs/enterprise/technical-integration). # Government and agency procurement Source: https://docs.truthlocks.com/packs/enterprise/b2g-procurement Assess Truthlocks for an agency deployment using explicit requirements, supported workflows and current evidence. Government agencies can evaluate Truthlocks for signed records, document verification and approval evidence. Procurement acceptance must use the actual deployment, current test evidence and written responsibilities. This page is not a claim of sovereign accreditation, government certification or an unconditional service-level guarantee. ## Evaluate the deployment The current hosted platform uses Google Cloud. Confirm the agreed data region, subprocessors, access boundaries, retention and exit arrangements before production use. A selectable region or a key-management feature does not establish sovereign hosting or a dedicated government deployment by itself. Workspace and environment controls protect supported operations. Request the applicable isolation test results and known limitations. Independently assess whether the available identity-review and approval workflows meet the agency's requirements; do not assume mandatory multi-person approval for every operation. ## Onboard and validate 1. Create the organization and complete the requested organization and identity evidence. 2. Use sandbox keys and synthetic records to test the integration. 3. Submit the issuer application and required evidence for staff review. Creating an issuer is not proof of a reviewed identity or production approval. 4. Select an algorithm supported by the chosen signing provider and test signature verification and tamper rejection. 5. Complete production onboarding and any separately required billing-country review before the relevant production or paid operation. 6. Review roles, MFA/SSO, audit exports, retention and incident contacts before inviting operational users. Use the [issuer application guide](/guides/issuer-applications), [security governance page](/enterprise/security-governance) and [SIEM delivery guide](/guides/siem-integration). Validate invitation delivery and access with the intended users; do not infer successful onboarding from tenant creation or a sales status change. ## Reliability and response Automated database backups and point-in-time recovery are configured. Full application recovery, availability commitments, support coverage and incident response times must be assessed and agreed explicitly. A single-zone database does not provide multi-zone database failover. This page does not promise a staffed 24/7 response team, multi-region failover or automatic service credits. Agree the required recovery objectives, escalation contacts, evidence retention and exit procedures in the contract. Record acceptance decisions and unresolved exceptions; a successful sandbox pilot does not waive them. # Enterprise Verification Packs Source: https://docs.truthlocks.com/packs/enterprise/overview Buyer-ready assets and onboarding kits tailored for Enterprise & Government partners. Buyer-ready assets and onboarding kits designed for Sales, CS, and Compliance teams to accelerate Truthlocks adoption across businesses and governments. ## Available Packs > **[B2B Onboarding Pack](/packs/enterprise/b2b-onboarding)** > > Business onboarding workflow, roles, and trust tiers. > **[B2G Procurement Pack](/packs/enterprise/b2g-procurement)** > > Architecture, privacy, and SLAs for government/institutions. > **[Technical Integration Pack](/packs/enterprise/technical-integration)** > > API reference, webhooks, and proof bundle validation. > **[Security & Compliance](/packs/enterprise/security-compliance)** > > Cryptographic model, RLS isolation, and audit trails. > **[Verification Program](/packs/enterprise/verification-program)** > > Operational guide for running verification programs. > [!NOTE] > > **Print Optimization:** Each of these guides is optimized for printing to PDF > natively through your browser (`Ctrl+P` or `Cmd+P`). # Security and assurance scope Source: https://docs.truthlocks.com/packs/enterprise/security-compliance Technical safeguards, shared responsibilities, and evidence to request before relying on an assurance claim. Truthlocks issues signed attestations and publishes transparency evidence. A valid signature establishes integrity and signing-key attribution; it does not by itself establish that a claim is true, an identity was independently verified, or a regulatory requirement was satisfied. ## Cryptography and keys Use the algorithms actually supported by the selected key provider and API. Truthlocks supports multiple signing algorithms; Ed25519 is not the only option. Managed platform signing uses Google Cloud KMS. Confirm the protection level and key-management responsibilities for the specific deployment rather than assuming every key is held in an HSM with a particular certification. Public proof identifiers and public verification keys are intentionally shareable. Private keys, API credentials and internal cloud key paths must not appear in public proof displays. Issuer-managed keys and platform-managed keys have different operational responsibilities. ## Tenant and environment boundaries Verified identities, API scopes and PostgreSQL row-level security protect workspace access. Signing resources and supported data paths distinguish sandbox from production. These controls require testing across each relevant API, job and storage path; they do not justify an absolute claim that cross-tenant access is impossible. Ask for the current isolation evidence and unresolved findings. ## Audit and transparency evidence The transparency log publishes signed checkpoints and inclusion evidence for logged records. Application audit events and request logs are separate evidence sources. [SIEM delivery](/guides/siem-integration) covers new audit events with verified environment attribution, not every historical platform action. Retention depends on the actual configured storage policy and agreement; this page does not promise seven years of complete audit history. ## Privacy and recovery Private document storage, audit retention, legal holds and erasure requests require distinct controls. An immutable signed record is not the same as a deletable uploaded document. Confirm the supported deletion/export workflow and the applicable retention policy before uploading regulated information. The current hosted database has automated backups and point-in-time recovery. A database recovery exercise is separate from application failover. Do not assume multi-region failover, a particular recovery time, or a guaranteed availability percentage from this page. Service levels and recovery commitments require a written agreement supported by the deployed architecture and exercises. ## Shared responsibilities Truthlocks operates the hosted platform and its managed keys. Customers control their users, API credentials, submitted claims and intended use. Responsibility for personal-data requests, customer-held keys, retention and incident communication must be defined in the applicable agreement. Read [security governance](/enterprise/security-governance) and [compliance scope](/trust/compliance). No completed SOC 2 examination, ISO/IEC 27001 certification, independent audit opinion or blanket regulatory compliance is asserted here. # Technical Integration Pack Source: https://docs.truthlocks.com/packs/enterprise/technical-integration Developer's Quickstart & API Strategy **Developer's Quickstart & API Strategy** ## 1. Authentication All API requests must be authenticated via Bearer tokens. * **API Keys**: Issued via the Tenant Console (Security > API Keys). * **Scopes**: Keys are scoped to specific actions (e.g., `mint`, `verify`, `read_audit`). * **Rotation**: We recommend a 90-day rotation policy. Invalidate keys immediately via the DELETE endpoint upon compromise. ## 2. The Minting Flow To issue an attestation, POST a JSON payload to `/v1/attestations/mint`. ```json theme={null} { "template_key": "academic_transcript", "payload": { "student_id": "STU123", "gpa": "3.8" }, "recipient_email": "student@university.edu" } ``` ## 3. Webhooks & Eventing Truthlocks uses webhooks to notify your system of state changes. | Event Type | Description | | :- | :- | | `attestation.created` | Triggered when the platform has signed the record. | | `issuer.suspended` | Triggered if the issuer's trust rating changes. | | `billing.usage.threshold` | Triggered when a usage threshold is reached. | **Verification**: Always verify the `X-Truthlocks-Signature` header using your endpoint's shared secret. See the [webhooks guide](/guides/webhooks) for full details on event types, signature verification, and retry behavior. ## 4. Proof Bundles A Proof Bundle is a signed JSON object containing: 1. **Original Data**: The payload you minted. 2. **Issuer Signature**: Your cryptographic proof of intent. 3. **Platform Checkpoint**: Truthlocks' proof of the network state at the time of minting. ## 5. Rate Limits & Quotas Limits are applied per-tenant based on your subscription tier: * **Global Burst**: 500 requests per 10 seconds. * **Monthly Minting Quota**: Defined in your Enterprise Agreement (viewable in `/v1/billing/usage`). *** ## 6. Environment Separation We provide two distinct environments: * **Sandbox (`sandbox.truthlocks.com`)**: For testing with mock keys and ephemeral data. * **Production (`api.truthlocks.com`)**: Federated for high-stakes issuing. > [!TIP] > > Use our [SDKs](/sdk/js) to handle retries, signature verification, and > payload serialization automatically. # Verification Program Guide Source: https://docs.truthlocks.com/packs/enterprise/verification-program Operational Blueprint for Proof-Based Trust **Operational Blueprint for Proof-Based Trust** ## 1. Introduction A Verification Program (VP) is a structured operational framework where an organization (the Issuer) provides digital, verifiable proof of state to consumers or partners (the Verifiers). ## 2. Program Design Successful programs follow a three-step design phase: 1. **Trust Tier Definition**: Determine which credentials require simple platform-attestation vs. deeper evidence-backed review. 2. **Payload Schema**: Standardize the JSON structure for attestations to ensure interoperability. 3. **Delivery Channel**: Choose between Email-based delivery (Consumer Inbox), Mobile App Pushes, or B2B API sync. ## 3. Operational Flow The "Mint-to-Verify" lifecycle in Truthlocks: * **Step 1: Event Capture**: Your internal system detects a "Verifiable Event" (e.g., a Diploma is issued). * **Step 2: Attestation Minting**: Call the Truthlocks `/mint` API with the relevant data. * **Step 3: Signature & Checkpoint**: Truthlocks signs the record and creates a transparent checkpoint. * **Step 4: Bundle Delivery**: Deliver the signed Proof Bundle to the recipient. * **Step 5: Verification**: The recipient (or a third-party partner) verifies the bundle via our Verify Portal or API. ## 4. Best Practices * **Use Webhooks**: Automate your system's response to `subscription.limit` warnings to avoid issuing interruptions. * **Transparency Logs**: Regularly audit your tenant's transparency checkpoints to ensure consistency with your internal records. * **Environment Parity**: Always test new attestation schemas in the Sandbox before production rollout. ## 5. Case Study: B2G Procurement An infrastructure agency issues "Safety Compliance Certificates" to contractors. * **Verifiers**: Mainline auditors and public safety inspectors. * **Benefit**: Zero-trust verification of contractor standing with no paper trail and real-time revocation support. *** > [!TIP] > > Use the **Consumer Portal** feature to allow your users to view and manage > their proof bundles in a centralized Truthlocks-hosted vault. # Policy engine Source: https://docs.truthlocks.com/policy Enterprise-grade policy evaluation for B2C, B2B, B2G, and B2B2C scenarios. Enforce compliance rules, trust requirements, and security policies across your ecosystem. Policies apply to three categories: `MINT`, `VERIFY`, and `BUNDLE_EXPORT`. > [!NOTE] > > Looking to set up rule-based policies from the console or API? See the [issuance policies guide](/guides/issuance-policies) for creating, managing, and simulating policies without writing code. ## Policy Templates > **B2C - Consumer** > > Consumer-focused policy with trust disclosure and risk protections. - Issuer > must be in trusted status - Trust tier must be verified\_org or higher - > Block high/critical risk issuers - Key must be active > **B2B - Enterprise** > > Business-to-business with industry requirements and key rotation. - Issuer > must be in trusted status - Finance/Healthcare require regulated\_issuer tier > > * Key rotation required every 180 days - Governance approvals for status > changes > **B2G - Government** > > Government-grade policy with strict compliance requirements. - All > attestations require regulated\_issuer tier - Block medium or higher risk > issuers - Key rotation required every 90 days - Mandatory documented > revocation reasons > **B2B2C - Hybrid** > > Hybrid policy for enterprise-to-consumer scenarios with dual disclosure. - > Issuer must be in trusted status - Trust tier must be verified\_org or higher > > * Privacy protection: payload not stored - Consumer-friendly + enterprise > audit details ## Usage ```javascript theme={null} import { EnterprisePolicyEngine, templates } from "@truthlock/policy"; // Create engine with B2B template const engine = new EnterprisePolicyEngine(templates.B2B); // Evaluate policy const result = engine.evaluate({ tenant_id: "tenant-uuid", issuer_current: { id: "issuer-uuid", status: "trusted", trust_tier: "verified_org", risk_rating: "low", jurisdiction: "US", assurance_level: "standard", }, key: { kid: "key-1", status: "ACTIVE", valid_from: "2024-01-01T00:00:00Z", age_days: 30, }, context: { request_type: "mint", industry: "technology", }, }); if (!result.allowed) { console.log("Denied:", result.code); console.log("Reason:", result.compliance_explanation); } ``` ## Policy Result ```typescript theme={null} interface PolicyResult { allowed: boolean; code: string; // e.g., "ISSUER_NOT_TRUSTED" reason: string; // Human-readable reason compliance_explanation: string; // Compliance-friendly explanation disclosures?: { type: "warning" | "info" | "critical"; message: string; audience: "consumer" | "enterprise" | "all"; }[]; } ``` ## Policy Versioning Each policy instance has a unique hash computed from the template and rules. This hash can be stored with attestations for audit purposes. ```javascript theme={null} const engine = new EnterprisePolicyEngine(templates.B2G); console.log("Policy hash:", engine.getPolicyHash()); // => "a1b2c3d4e5f6g7h8" console.log("Policy version:", engine.getPolicyVersion()); // => "1.0.0-1704067200000" ``` ## Policy categories | Category | Applies to | | - | - | | `MINT` | Attestation minting requests | | `VERIFY` | Verification requests | | `BUNDLE_EXPORT` | Proof-bundle export and data-portability requests | `BUNDLE_EXPORT` policies are evaluated whenever a user or API client requests a proof bundle download or submits a data-portability export. Use them to restrict exports by jurisdiction, trust tier, risk rating, or any other field available in the evaluation context. See [export control policies](/guides/issuance-policies#export-control-policies) for examples. ## Policy lifecycle Every policy has a status that controls enforcement: | Status | Behavior | | - | - | | `DRAFT` | Saved but not enforced — use while iterating on rules | | `ACTIVE` | Enforced on every matching request | | `DISABLED` | Temporarily turned off without deleting | Only `ACTIVE` policies are evaluated at request time. Each status change increments the policy version, which is recorded alongside every evaluation decision for auditability. A typical lifecycle: 1. **Create as `DRAFT`** — build and refine rules without affecting live traffic. 2. **Simulate** — test the policy against sample inputs. 3. **Set to `ACTIVE`** — enforcement begins immediately. 4. **Set to `DISABLED`** — pause enforcement without losing the policy definition. 5. **Delete** — remove the policy when no longer needed. > [!NOTE] > > See the [issuance policies guide](/guides/issuance-policies#policy-lifecycle) for step-by-step instructions on managing policy status transitions. ## Simulating policies Test how a policy evaluates a given input before deploying it. See the [policy simulator](/guides/issuance-policies#simulating-a-policy) for console and API usage. # Quick Start Source: https://docs.truthlocks.com/quickstart Mint and verify a record using your workspace issuer and signing key. An attestation signs a payload and records its hash. Verification checks cryptographic integrity and record status; it does not independently establish that the issuer's claims are true. ## Before you start In [Console](https://console.truthlocks.com), select your workspace and environment. Obtain an API key, issuer ID, and an active key available for server-side signing. Use the algorithm shown for that key. Registering a public key alone does not give the signing service its private key. Use `https://sandbox-api.truthlocks.com` with a sandbox key (`tl_test_`). Use `https://api.truthlocks.com` with a production key (`tl_live_`) and an approved workspace. Resources and credentials must belong to the same environment. Do not send `X-Tenant-ID` to choose a workspace: it is derived from your credentials. ## Mint a record This example uses Python 3's standard library. Set the four required environment variables through your shell or secret manager. Set `TRUTHLOCKS_BASE_URL` only if changing from sandbox to production. ```python theme={null} import base64 import json import os import urllib.request import uuid base_url = os.environ.get("TRUTHLOCKS_BASE_URL", "https://sandbox-api.truthlocks.com").rstrip("/") payload = json.dumps({"subject": "demo-record", "message": "Example issuer claim"}, separators=(",", ":")).encode("utf-8") body = { "issuer_id": os.environ["TRUTHLOCKS_ISSUER_ID"], "kid": os.environ["TRUTHLOCKS_KEY_ID"], "alg": os.environ["TRUTHLOCKS_ALGORITHM"], "content_type": "application/json", "payload_b64url": base64.urlsafe_b64encode(payload).decode("ascii").rstrip("="), } # Retain this value and the same body if retrying this mint request. idempotency_key = str(uuid.uuid4()) request = urllib.request.Request( base_url + "/v1/attestations/mint", data=json.dumps(body).encode("utf-8"), headers={"Content-Type": "application/json", "X-API-Key": os.environ["TRUTHLOCKS_API_KEY"], "Idempotency-Key": idempotency_key}, method="POST", ) with urllib.request.urlopen(request, timeout=30) as response: record = json.load(response) print("Attestation ID:", record["attestation_id"]) print("Recorded at (Unix seconds):", record["issued_at_unix"]) ``` HTTP errors raise `urllib.error.HTTPError`. Handle errors and timeouts in your application; preserve the same idempotency key and body when retrying an uncertain mint outcome. The response uses `attestation_id`, `issued_at_unix`, `signature`, and `log`. It does not echo the claims as a top-level `payload`. Keep the original bytes for subsequent integrity checks. ## Verify the result Use the [verification reference](/api-reference/verify) with the returned `attestation_id`. Supply `payload_b64url` to check the exact original bytes, or `document_hash_hex` to compare a file hash. Inspect `verdict` and `reasons`: a successful HTTP response alone does not mean the record is valid. ## Troubleshooting * **401 or 403:** check credentials, environment, permissions, and workspace approval. * **400:** check UUIDs, the idempotency header, and unpadded base64url encoding. * **Key or policy error:** confirm the issuer and key are usable for signing and the algorithm matches. * **Timeout:** retry with the original body and idempotency key, rather than creating a new mint. Continue with [mint parameters](/api-reference/attestations/mint), [authentication](/security/auth), and [environments](/environments). # Go SDK Source: https://docs.truthlocks.com/sdk/go The source contains a root `truthlock` package and a legacy `pkg` client. They are different interfaces; do not mix method names or request types from one with the other. The root module path is: ```text theme={null} github.com/truthlocks/sdk-go ``` Install the corrected public module with `go get github.com/truthlocks/sdk-go@v0.4.0`. Older tags used an incompatible module path. ## Client configuration ```go theme={null} client := truthlock.NewClient(truthlock.Config{ BaseURL: "https://sandbox-api.truthlocks.com", APIKey: os.Getenv("TRUTHLOCKS_API_KEY"), }) ``` This is a fragment for a Go program importing the module, `os`, and `context`. Use a key matching the host. Tenant ID alone is not authentication; the server derives the workspace from the credential. ## Minting The root client accepts `MintRequest` with `IssuerID`, `KID`, `Alg`, and `PayloadB64URL`. Encode original bytes with `base64.RawURLEncoding.EncodeToString`. Alternatively, set `Schema` and `Claims` and leave `PayloadB64URL` empty to use structured input. Do not combine the two input modes. ```go theme={null} record, err := client.Attestations.Mint(ctx, &truthlock.MintRequest{ IssuerID: os.Getenv("TRUTHLOCKS_ISSUER_ID"), KID: os.Getenv("TRUTHLOCKS_KEY_ID"), Alg: truthlock.Algorithm(os.Getenv("TRUTHLOCKS_ALGORITHM")), PayloadB64URL: base64.RawURLEncoding.EncodeToString([]byte(`{"subject":"demo-record"}`)), }) if err != nil { return err } fmt.Println(record.AttestationID) ``` This fragment belongs in a function returning `error`; import `encoding/base64` and `fmt`, and provide `ctx`. Use an issuer and signing key already provisioned for the environment. ## Request and response contracts The corrected root transport performs HTTP requests and surfaces HTTP and JSON errors. Earlier source snapshots contained a no-op transport; do not treat a successful return from such a version as evidence that a request reached Truthlocks. Verify your pinned source version. Keep a stable idempotency key across retries of one write and the same body. Do not assume a new SDK method call reuses the previous key. Handle cancellation and errors explicitly; never discard mint or verification errors. Use the [API reference](/api-reference/attestations/mint) for wire fields and the [direct HTTP quickstart](/quickstart) when checking a package version's behavior. # JavaScript / TypeScript SDK Source: https://docs.truthlocks.com/sdk/js Install the public package: ```bash theme={null} npm install @truthlocks/sdk@^2.1.0 ``` Use Node.js 18 or later. The core resources are `issuers`, `keys`, `attestations`, `verify`, `audit`, and `receipts`. Do not assume every public API has a convenience method in this package; use the operation reference and `client.request` where appropriate. ## Configure authentication ```typescript theme={null} import { TruthlockClient } from '@truthlocks/sdk'; const apiKey = process.env.TRUTHLOCKS_API_KEY; if (!apiKey) throw new Error('Set TRUTHLOCKS_API_KEY'); const client = new TruthlockClient({ baseUrl: 'https://sandbox-api.truthlocks.com', auth: { type: 'service', apiKey }, }); ``` The API-key strategy is `service`, not `apiKey`. For a user operation use `auth: { type: 'bearer', token }` with a valid user token. `tenantId` does not authenticate or switch workspaces. Do not use tenant-only authentication. ## Mint Use an existing issuer and a key available for server-side signing. Use either encoded original bytes or structured `schema` and `claims` input. ```typescript theme={null} const payload = Buffer.from(JSON.stringify({ subject: 'demo-record' }), 'utf8'); const record = await client.attestations.mint({ issuer_id: process.env.TRUTHLOCKS_ISSUER_ID!, kid: process.env.TRUTHLOCKS_KEY_ID!, alg: process.env.TRUTHLOCKS_ALGORITHM!, payload_b64url: payload.toString('base64url'), }); console.log(record.attestation_id); ``` Set all three environment variables before running the snippet. For structured input, replace `payload_b64url` with `schema: "attestation"` and `claims: { subject: "demo-record" }`; never send both modes. Public-key registration alone does not provision a signing private key. ## Retries and response handling The client adds an idempotency header to POST and PUT requests. A new method call generates a new key, so it is not a safe retry of an uncertain earlier write unless you retain and pass the same key. `client.request` accepts an `idempotencyKey` option. Automatic retries are limited to reads and supported attestation/receipt writes with an explicit key; arbitrary writes are not replayed simply because a key was provided. Inspect verification `verdict` and `reasons`. A resolved promise or HTTP 200 alone is not a valid-verification result. Match the installed package version with its type declarations; newly corrected source is not evidence that an older installed release contains the fixes. See the [direct HTTP example](/guides/sdk-examples) for a dependency-independent integration and [API reference](/api-reference/attestations/mint) for the current contract. # Python SDK Source: https://docs.truthlocks.com/sdk/python Install the distribution whose source package is `truthlock`: ```bash theme={null} python -m pip install "truthlock>=0.4.0" ``` The import is `from truthlock import TruthlockClient`. Package names for MAIP integrations are separate distributions and do not imply the same API. ## Mint with an existing signing key ```python theme={null} import base64 import json import os from truthlock import TruthlockClient payload = json.dumps({"subject": "demo-record"}, separators=(",", ":")).encode("utf-8") with TruthlockClient( api_key=os.environ["TRUTHLOCKS_API_KEY"], base_url="https://sandbox-api.truthlocks.com", ) as client: record = client.attestations.mint( issuer_id=os.environ["TRUTHLOCKS_ISSUER_ID"], kid=os.environ["TRUTHLOCKS_KEY_ID"], alg=os.environ["TRUTHLOCKS_ALGORITHM"], payload_b64url=base64.urlsafe_b64encode(payload).decode("ascii").rstrip("="), ) print(record.attestation_id) ``` Set the four environment variables first. Use a sandbox key, issuer, and key available for signing in that environment. Public-key registration does not provision a private signing key. ## Verify Call `client.verify.verify_online(attestation_id=record.attestation_id)` and inspect the verdict. Add `payload_b64url` when checking the original bytes. The backend uses uppercase wire verdicts; the corrected SDK normalizes them to its lowercase enum values. Version 0.4.0 and later include the corrected verdict parsing. ## Version and retry boundaries The implemented core resource groups are `issuers`, `keys`, `attestations`, `verify`, and `receipts`. Do not call hypothetical `consumer`, `governance`, or `audit` resource methods on this client. Minting generates an idempotency header. Retrying the same internal request can retain it, but calling mint again creates a new operation unless the same key is supplied. Preserve keys and request bodies in durable application jobs. A timeout does not prove that a write failed. Use the [HTTP quickstart](/quickstart) to compare a release with the actual wire contract. Install version 0.4.0 or later to use the corrected transport and proof-bundle fields. # Abuse Hardening & Security Controls Source: https://docs.truthlocks.com/security/abuse-hardening Enterprise-grade protections against DoS, abuse, and noisy tenants. Multi-tenant fairness with per-IP and per-tenant rate limiting. Enterprise-grade protections against DoS, abuse, and noisy tenants. Multi-tenant fairness with per-IP and per-tenant rate limiting. ## Rate Limiting | Route Class | Limit Type | Rate | Burst | | - | - | - | - | | Public Verify | Per-IP | 50 r/s | 20 | | Minting | Per-Tenant | 20 r/s | 10 | | Governance | Per-Tenant | 10 r/s | 5 | | General API | Per-IP | 100 r/s | 50 | ## Request Size Limits | Endpoint | Max Body Size | | - | - | | Global Default | 1 MB | | `/v1/attestations` | 512 KB | ## Error Responses | HTTP | Code | Description | | - | - | - | | 413 | `PAYLOAD_TOO_LARGE` | Request body exceeds size limit | | 429 | `RATE_LIMIT_EXCEEDED` | Too many requests | | 503 | `SERVICE_UNAVAILABLE` | Upstream temporarily unavailable | ```json theme={null} { "code": "RATE_LIMIT_EXCEEDED", "message": "Too many requests. Please retry after the specified interval.", "http_status": 429, "retry_after_ms": 1000 } ``` ## Connection timeout protection All API services enforce HTTP server timeouts that protect against slowloris-style denial-of-service attacks. These timeouts automatically close connections that send data too slowly, preventing a single attacker from exhausting server resources with many slow, open connections. This protection applies to every service behind the API gateway and requires no configuration on your part. If you are running long-polling or streaming requests, ensure your client sends data within the standard HTTP timeout window. Standard API requests are not affected. ## Algorithm Enforcement > [!WARNING] > > **Algorithm Enforcement:** The platform supports Ed25519, ES256, ES384, ES512, RS256, RS384, RS512, PS256, PS384, PS512. Requests with algorithms outside this set will be > rejected with a `400` error. ## Compliance Mapping > **B2C** > > * Per-IP limits protect consumer endpoints \* Privacy-first: only hashes > logged \* Rate limits explained as consumer protection > **B2B** > > * Per-tenant quotas for SLA isolation \* Audit retention for enterprise > audits \* Correlation IDs for SOC2/ISO27001 > **B2G** > > * Stricter governance route limits \* Retention supports regulatory > recordkeeping \* Error taxonomy for legal defensibility > **B2B2C** > > * Dual-layer limits (IP + tenant) \* Offline bundle verification \* Cross-org > portability ## Configuration ```nginx # Gateway (nginx.conf) theme={null} client_max_body_size 1m; limit_req_zone $binary_remote_addr zone=per_ip_verify:10m rate=50r/s; limit_req_zone $tenant_key zone=per_tenant_mint:10m rate=20r/s; # Audit Service AUDIT_RETENTION_DAYS=90 # Transparency Log LOG_CHECKPOINT_INTERVAL=5m LOG_PRUNE_KEEP_LEAVES=1000 ``` # Audit Logs Source: https://docs.truthlocks.com/security/audit Track all API activity, security events, and compliance auditing. Truthlocks maintains comprehensive audit logs for security monitoring, compliance reporting, and operational troubleshooting. ## What's Logged Every API operation generates an audit event. This includes successful operations, failed attempts, and security-relevant events. > **API Operations** > > * Attestation minting \* Attestation revocation \* Issuer > creation/modification \* Key registration > **Security Events** > > * Authentication failures \* Permission denied \* Rate limit exceeded \* > Suspicious activity > **Governance Actions** > > * Issuer approval/rejection \* Issuer suspension \* Role assignments \* API key > management > **User Activity** > > * User login/logout \* Password changes \* User invitations \* Role changes ## Audit Event Structure Each audit event contains detailed context about what happened, who did it, and when: ```json theme={null} { "id": "evt_abc123", "timestamp": "2026-01-13T12:34:56.789Z", "tenant_id": "tenant-uuid", "actor_type": "USER", "actor_id": "user-uuid", "action": "attestation.mint", "resource_type": "attestation", "resource_id": "attestation-uuid", "service": "trust-registry", "outcome": "SUCCESS", "metadata": { "issuer_id": "issuer-uuid", "subject": "user:12345", "claim": "email_verified" }, "integrity_hash": "sha256:abc123..." } ``` | Field | Type | Description | | - | - | - | | `actor_type` | string | Who performed the action: `USER`, `API_KEY`, or `SERVICE` | | `actor_id` | string | UUID of the user, API key, or service that triggered the event | | `action` | string | The operation performed (e.g., `attestation.mint`) | | `resource_type` | string | Type of resource affected (e.g., `attestation`, `issuer`, `user`) | | `resource_id` | string | UUID of the affected resource | | `service` | string | The backend service that handled the request (e.g., `trust-registry`, `audit-service`) | | `outcome` | string | `SUCCESS` or `FAILURE` | | `metadata` | object | Action-specific context such as issuer ID, claim type, or error details | | `integrity_hash` | string | SHA-256 hash for tamper-evidence verification | ## Querying Audit Logs ### Basic Query ```bash theme={null} curl -X GET "https://api.truthlocks.com/v1/audit/events?limit=100" \ -H "X-API-Key: tl_live_your_api_key" ``` ### Filtered Query ```bash theme={null} curl -X GET "https://api.truthlocks.com/v1/audit/events" \ -H "X-API-Key: tl_live_your_api_key" \ -G \ --data-urlencode "action=attestation.mint" \ --data-urlencode "actor_id=user-uuid" \ --data-urlencode "from=2026-01-01T00:00:00Z" \ --data-urlencode "to=2026-01-31T23:59:59Z" \ --data-urlencode "limit=50" ``` ### Filter Parameters | Parameter | Type | Description | | - | - | - | | `action` | string | Filter by action type (e.g., `attestation.mint`) | | `actor_id` | string | Filter by user or API key ID | | `resource_type` | string | Filter by resource (attestation, issuer, user) | | `from` | datetime | Events after this time (ISO 8601) | | `to` | datetime | Events before this time (ISO 8601) | | `limit` | integer | Max events to return (default 50, max 1000) | | `cursor` | string | Pagination cursor for next page | ## Policy decision audit trail Every [issuance policy](/guides/issuance-policies) evaluation is automatically recorded as an audit event. Each record captures the `decision_id`, policy version, matched rules, evaluation time, and a SHA-256 hash of the input for tamper-evidence. Query policy decisions by filtering on `resource_type=policy_decision`: ```bash theme={null} curl "https://api.truthlocks.com/v1/audit/events?resource_type=policy_decision&resource_id=dec_7f3a1b" \ -H "X-API-Key: tl_live_..." ``` See [decision audit trail](/guides/issuance-policies#decision-audit-trail) for the full list of recorded fields. ## Common use cases ### Security investigation Find all failed authentication attempts for a specific actor: ```http theme={null} GET /v1/audit/events ?action=auth.failure &actor_id=user-uuid &from=2026-01-12T00:00:00Z ``` ### Compliance Report Export all attestation operations for a time period: ```http theme={null} GET /v1/audit/events ?resource_type=attestation &from=2026-01-01T00:00:00Z &to=2026-01-31T23:59:59Z &limit=1000 ``` ### User Activity Review See everything a specific user did: ```http theme={null} GET /v1/audit/events ?actor_id=employee-uuid &limit=100 ``` ## Log retention | Tier | Default retention | Export format | | - | - | - | | Free | 7 days | JSON only | | Starter | 30 days | JSON, CSV | | Professional | 90 days | JSON, CSV, SIEM integration | | Enterprise | 1 year (custom available) | All formats + real-time streaming | > [!NOTE] > > For compliance requirements exceeding your tier's > retention period, configure SIEM integration to stream logs to your own > infrastructure. ### Custom retention policies You can configure how long audit logs are retained and whether expired logs are archived or permanently deleted. Set retention policies globally or per environment. | Field | Type | Description | | :- | :- | :- | | `retention_days` | integer | Days to keep audit logs (30–3,650) | | `hard_delete` | boolean | If `true`, permanently delete expired logs. If `false`, archive them. | | `export_allowed` | boolean | Whether audit exports are permitted for this scope | | `environment_id` | string | Optional. Apply this policy to a specific environment only. | The default policy retains logs for 365 days, archives (soft-deletes) expired logs, and allows exports. **Get your current retention policy:** ```bash theme={null} curl https://api.truthlocks.com/v1/audit/retention \ -H "X-API-Key: tl_live_..." ``` ```json theme={null} { "retention_days": 365, "hard_delete": false, "export_allowed": true, "environment_id": null } ``` **Update the retention policy:** ```bash theme={null} curl -X PUT https://api.truthlocks.com/v1/audit/retention \ -H "X-API-Key: tl_live_..." \ -H "Content-Type: application/json" \ -d '{ "retention_days": 730, "hard_delete": false, "export_allowed": true }' ``` When an environment-specific policy exists, it takes precedence over the global policy. If no environment-specific policy is set, the global policy applies. > [!WARNING] > > Changing `hard_delete` to `true` permanently removes logs once they pass the retention window. This action cannot be undone. Make sure you have exported any logs you need before enabling hard delete. Updating retention settings requires the `tenant.audit.retention.manage` permission. Viewing settings requires `tenant.audit.retention.read`. ## SIEM Integration Enterprise customers can stream audit logs in real-time to external security information and event management (SIEM) systems. ### Supported providers | Provider | Transport | Format | | :- | :- | :- | | **Splunk** | HTTP Event Collector (HEC) | JSON | | **Datadog** | Log Management API | JSON | | **AWS CloudWatch** | Logs subscription | JSON | | **Elastic/ELK** | Elasticsearch ingest | JSON | | **Custom webhook** | HTTP POST | JSON | Configure a streaming destination from **Settings > Audit > SIEM** in the console, or manage destinations programmatically through the [SIEM configuration API](/api-reference/audit/siem/create). For step-by-step provider setup instructions, see the [SIEM integration guide](/guides/siem-integration). ### Create a SIEM destination ```bash theme={null} curl -X POST https://api.truthlocks.com/v1/audit/siem \ -H "X-API-Key: tl_live_..." \ -H "Content-Type: application/json" \ -d '{ "provider": "splunk", "endpoint": "https://hec.splunk.example.com:8088/services/collector", "token": "your-hec-token", "enabled": true }' ``` ```json theme={null} { "id": "siem_abc123", "provider": "splunk", "endpoint": "https://hec.splunk.example.com:8088/services/collector", "enabled": true, "created_at": "2026-06-30T12:00:00Z", "status": "active" } ``` Replace `provider` with one of `splunk`, `datadog`, `cloudwatch`, `elastic`, or `webhook`. Each provider requires a destination `endpoint` and an authentication credential (`token` for Splunk, Datadog, and Elastic; `access_key_id` and `secret_access_key` for CloudWatch; `secret` for custom webhooks). ### List SIEM destinations Retrieve all configured streaming destinations for your tenant. ```bash theme={null} curl https://api.truthlocks.com/v1/audit/siem \ -H "X-API-Key: tl_live_..." ``` ### Update a SIEM destination Change the endpoint, credentials, or enabled state of an existing destination. ```bash theme={null} curl -X PUT https://api.truthlocks.com/v1/audit/siem/siem_abc123 \ -H "X-API-Key: tl_live_..." \ -H "Content-Type: application/json" \ -d '{ "endpoint": "https://hec-new.splunk.example.com:8088/services/collector", "token": "your-new-hec-token", "enabled": true }' ``` ### Delete a SIEM destination Remove a streaming destination. In-flight events are flushed before the destination is deleted. ```bash theme={null} curl -X DELETE https://api.truthlocks.com/v1/audit/siem/siem_abc123 \ -H "X-API-Key: tl_live_..." ``` ### Delivery and buffering Once enabled, every audit event is streamed to your destination in real time alongside the standard in-platform log. If the destination is unreachable, events are buffered and retried with exponential backoff for up to 24 hours. You can monitor delivery health in the `status` field returned by the list endpoint — possible values are `active`, `degraded` (retrying), and `failed`. > [!WARNING] > > **Enterprise feature:** Real-time log streaming requires the Enterprise tier. > Contact sales for setup assistance. ## Next steps > **[SIEM integration](/guides/siem-integration)** > > Stream audit events to Splunk, Datadog, CloudWatch, Elastic, or a custom webhook. > **[Compliance exports](/guides/compliance-exports)** > > Export audit data in SOC 2, GDPR, and HIPAA formats. > **[Abuse hardening](/security/abuse-hardening)** > > Detect and prevent abuse using audit data. > **[Rate limits](/ops/limits)** > > Understand rate limiting behavior in audit logs. # Authentication Source: https://docs.truthlocks.com/security/auth API authentication methods, key management, and security best practices. Truthlocks supports multiple authentication methods to secure API access. This guide covers API keys, JWT tokens, and security best practices. ## Authentication Methods > **API Keys** > > Long-lived credentials for server-to-server communication. Recommended for > backend services. > **Bearer Tokens (JWT)** > > Short-lived tokens for authenticated users. Ideal for frontend applications > and user context. ## API keys Truthlocks has two types of API keys depending on how you use the platform: | Type | Prefix | Created from | Use case | | :- | :- | :- | :- | | **Tenant key** | `tl_live_` / `tl_test_` | [Console](https://console.truthlocks.com) | Server-to-server integrations, enterprise workflows | | **Consumer key** | `tlk_` | [Verify portal](https://verify.truthlocks.com) | Personal API access for content protection and verification | ### Passing your key Include your API key using either of these headers: ```bash theme={null} curl -X GET https://api.truthlocks.com/v1/issuers \ -H "X-API-Key: tl_live_your_api_key" ``` You can also use the `Authorization` header with the `ApiKey` scheme: ```bash theme={null} curl -X GET https://api.truthlocks.com/v1/issuers \ -H "Authorization: ApiKey tl_live_your_api_key" ``` These formats authenticate API-key-enabled endpoints. Some operations require a user bearer token and role checks; public health endpoints need neither. `X-API-Key` is more common in examples throughout this documentation. ## Tenant API keys Tenant keys are the primary authentication method for organizations using Truthlocks. They are scoped to a tenant and support fine-grained permissions. ### Key structure ```text theme={null} tl_live_abc123def456gh789ijklmnopqrstuv │ │ │ │ │ └── 32-character random identifier │ └── Environment: test | live └── Prefix: tl (Truthlocks) ``` ### Scopes Tenant API keys can be restricted to specific permissions: | Scope | Permissions | | - | - | | `attestations:mint` | Create new attestations | | `attestations:read` | Read attestation details and proof bundles | | `attestations:revoke` | Revoke attestations | | `issuers:read` | View issuer information | | `issuers:write` | Create and manage issuers | | `users:read` | View users and roles | | `users:write` | Invite users, manage roles | | `audit:read` | Query audit logs | > [!NOTE] > > **Principle of least privilege:** Only grant the scopes your application > actually needs. A key with `attestations:mint` only should not also have > `users:write`. ### Creating a tenant key #### Via console 1. Navigate to [console.truthlocks.com/api-keys](https://console.truthlocks.com/api-keys) 2. Click "Create API Key" 3. Enter a descriptive name (e.g., "Production Backend") 4. Select the environment (production or sandbox) and required scopes 5. Copy the key immediately — it won't be shown again #### Via API ```bash Request theme={null} curl -X POST https://api.truthlocks.com/v1/api-keys \ -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..." \ -H "Content-Type: application/json" \ -d '{ "name": "Production Backend", "scopes": ["attestations:mint", "attestations:read", "issuers:read"] }' ``` ```json Response theme={null} { "id": "key-uuid", "name": "Production Backend", "prefix": "tl_live_abc", "secret": "tl_live_abc123def456gh789ijklmnopqrstuv", "scopes": ["attestations:mint", "attestations:read", "issuers:read"], "created_at": "2026-01-13T12:00:00Z" } ``` > [!WARNING] > > **Critical:** The `secret` field is only returned once at creation time. Store > it immediately in a secrets manager. ## Consumer API keys Consumer keys let individual users access the protect and verify APIs programmatically — for example, to mint attestations from a CI pipeline or integrate content protection into your own tools. ### Key details * Each account supports up to **5 active keys**. * Keys expire automatically after **90 days**. * Revoked or expired keys cannot be reactivated — create a new one instead. ### Fixed scopes Consumer keys are issued with a fixed set of scopes that cannot be customized: | Scope | Permissions | | :- | :- | | `consumer:read` | Read your consumer profile and settings | | `consumer:write` | Update your consumer profile and settings | | `attestations:mint` | Mint new attestations | | `attestations:read` | Read your attestations | | `verify:read` | Verify attestations | ### Creating a consumer key **1. Open settings** In the verify portal sidebar, go to **Settings > API Keys**. **2. Create a key** Click **Create API Key**, enter a descriptive name, and confirm. The full secret is displayed once — copy and store it securely. **3. Use the key** Pass the key in the `X-API-Key` header with every request: ```bash theme={null} curl -X GET https://api.truthlocks.com/v1/consumer/protections \ -H "X-API-Key: tlk_your_key_here" ``` For full details on managing consumer keys, see the [consumer portal guide](/guides/consumer-portal#api-keys). ## Bearer Tokens (JWT) JWT tokens are used when you need to make API calls on behalf of an authenticated user, such as from a web or mobile application. ### Using Bearer Tokens ```bash theme={null} curl -X GET https://api.truthlocks.com/v1/me \ -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..." ``` ### Token Structure ```json theme={null} { "sub": "user-uuid", "tenant_id": "tenant-uuid", "email": "user@example.com", "roles": ["admin"], "iat": 1705147200, "exp": 1705150800, "iss": "https://auth.truthlocks.com" } ``` ### Token Lifetime | Token Type | Lifetime | Refresh | | - | - | - | | Access Token | 1 hour | Via refresh token | | Refresh Token | 30 days | Via re-authentication | ## Authenticator MFA for Console accounts In Console, open **Settings → Security → Authenticator MFA** to connect Google Authenticator or another time-based authenticator app. 1. Confirm your current local Truthlocks password. 2. Scan the private QR code, or enter the setup key in your authenticator as a time-based account. 3. Enter the six-digit code from the app to enable MFA. 4. Save the ten recovery codes shown after confirmation. They are displayed once, and each code works once. New sign-ins require the second factor after either your password or your business identity provider. The verification step expires after five minutes. Repeated incorrect codes temporarily lock verification for the account. A code that has already been accepted cannot be reused. To replace recovery codes or disable MFA, confirm your password and a fresh authenticator code or unused recovery code. Replacing recovery codes invalidates the previous set. SSO users who have never set a local Truthlocks password can use the password-reset flow for their registered email before enrollment. MFA enrollment applies to your own account. It does not enroll other members or impose a workspace-wide MFA requirement. Enabling MFA does not automatically revoke existing sessions. API keys remain separate system credentials. ## Security Best Practices > **✅ Use Secrets Management** > > Store API keys in Google Secret Manager, HashiCorp Vault, or similar. Never > hardcode keys in application code. > **✅ Rotate Keys Regularly** > > Create new keys and revoke old ones periodically. Use descriptive names with > dates (e.g., "Backend-2026-Q1"). > **✅ Restrict Scopes** > > Only grant permissions that are actually needed. Review and audit key scopes > regularly. > **❌ Never Expose in Frontend** > > API keys should never be included in client-side JavaScript. Use JWT tokens > for frontend authentication. > **❌ Never Commit to Git** > > Use environment variables or secrets management. Add `.env*` to > `.gitignore`. ## Next steps > **[Consumer portal](/guides/consumer-portal)** > > Manage consumer API keys, protections, and settings. > **[Environments](/environments)** > > Sandbox vs. production configuration and base URLs. > **[RBAC & permissions](/security/rbac)** > > Understand roles, permissions, and access control. > **[Audit logs](/security/audit)** > > Track all API activity and security events. # Data location and account regions Source: https://docs.truthlocks.com/security/data-residency Distinguish region preferences from infrastructure residency commitments. An account's `region_code` is application metadata. Selecting a country or account region does not by itself deploy an isolated regional stack, migrate stored records, or restrict every processor to that region. The current recovery deployment uses Google Cloud. Do not rely on earlier documentation naming AWS regions in Virginia, Dublin, or Cape Town as evidence of available Truthlocks deployments. ## Before choosing a residency requirement Obtain confirmation of the actual locations and processors used for your workspace's database, object storage, backups, logging, email, billing, and AI features. A database location alone does not establish where all related data is processed. Changing a profile's region preference is not a data migration. If a location restriction is required by your organization, arrange and verify the deployment and processing terms before submitting restricted data. Public proof material, documentation, and content you deliberately publish have a different visibility boundary from private workspace records. Review what you publish and which downstream services receive it. See [security architecture](/trust/security), [tenant isolation](/security/rls), and [consumer profile updates](/api-reference/consumer/profile-update). # Email delivery Source: https://docs.truthlocks.com/security/email-delivery Understand notification outcomes and current email configuration. The current platform sends transactional email through Zoho SMTP. Earlier AWS SES setup instructions do not describe this deployment. Messages may use a Truthlocks alias such as `noreply@truthlocks.com`. Sender aliases and the authenticated SMTP mailbox are distinct; applications must authenticate with the configured mailbox, not assume an alias has separate credentials. ## Delivery outcomes A successful mint or account operation does not necessarily confirm inbox delivery. Notifications can be asynchronous, and SMTP acceptance does not prove the recipient read or received the message. Check the recipient address, mailbox folders, and delivery records when troubleshooting. ## Integration guidance Store SMTP and API credentials in a secret manager. Never put them in client-side code, documentation examples, or a public request body. Use actual delivery tests only with authorized recipient addresses. Provider-specific suppression, bounce ingestion, custom workspace SMTP, and retry behavior must be checked against the enabled deployment. Their presence in older documentation is not evidence that each integration is active. # RBAC & Permissions Source: https://docs.truthlocks.com/security/rbac Role-based access control and permission management. Truthlocks implements role-based access control (RBAC) to manage who can perform which actions. This guide explains the permission model. ## Permission Model The Truthlocks permission model consists of three layers: **1. Permissions** Atomic actions like `attestations:mint` or `users:read`. These are the building blocks. **2. Roles** Collections of permissions grouped by function. Roles like `admin`, `issuer`, or `viewer`. **3. Assignments** Binding users or API keys to roles. A user can have multiple roles. ## Available Permissions ### Attestation Permissions | Permission | Description | | - | - | | `attestations:mint` | Create new attestations | | `attestations:read` | View attestation details and download proof bundles | | `attestations:revoke` | Revoke existing attestations | | `attestations:*` | All attestation permissions | ### Issuer Permissions | Permission | Description | | - | - | | `issuers:read` | View issuer information and keys | | `issuers:write` | Create issuers, register keys | | `issuers:*` | All issuer permissions | ### User Management Permissions | Permission | Description | | - | - | | `users:read` | View users and role assignments | | `users:write` | Invite users, assign roles, remove users | | `api-keys:read` | View API keys (without secrets) | | `api-keys:write` | Create and revoke API keys | ### Administrative Permissions | Permission | Description | | - | - | | `audit:read` | Query audit logs | | `governance:approve` | Approve governance requests | | `governance:suspend` | Suspend active issuers | | `*` | Superadmin: all permissions | ### Webhook permissions | Permission | Description | | - | - | | `webhooks:read` | View webhook endpoints and delivery logs | | `webhooks:write` | Create, update, and delete endpoints | | `webhooks:*` | All webhook permissions | ### Governance permissions | Permission | Description | | - | - | | `governance:read` | View governance requests | | `governance:approve` | Approve governance requests | | `governance:suspend` | Suspend active issuers | | `governance:*` | All governance permissions | ### Settings permissions | Permission | Description | | - | - | | `settings:read` | View tenant and organization settings | | `settings:write` | Update branding, domains, email, and other settings | | `settings:*` | All settings permissions | ## System roles Truthlocks provisions a set of system roles automatically when your tenant is created. System roles cannot be edited or deleted. | Role | Description | Key permissions | | :- | :- | :- | | **Tenant Admin** | Full access to all resources within the tenant | `*` (superadmin) | | **Org Admin** | Manage a single organization's issuers, users, and attestations | `issuers:*`, `attestations:*`, `users:*`, `audit:read` | | **Issuer Admin** | Manage issuers and mint attestations | `issuers:*`, `attestations:*` | | **Auditor** | Read-only access for monitoring and compliance | `attestations:read`, `issuers:read`, `audit:read` | You can view system roles from the **Roles** page in the console. Each role shows its name, description, and a **System** badge. ## Custom roles Create custom roles to define access permissions tailored to your team's structure. Custom roles are available on all plans. ### Creating a custom role in the console **1. Open the Roles page** Navigate to **Roles** in the console sidebar. **2. Click Create Custom Role** The **Create Custom Role** button opens a dialog where you provide: * **Role Name** — a descriptive name for the role (for example, `Developer` or `Compliance Officer`). * **Description** — a brief explanation of what the role is for. **3. Save the role** Click **Create Role** to save. The new role appears in the **Custom Roles** section of the Roles page. ### Creating a custom role via the API ```bash theme={null} curl -X POST https://api.truthlocks.com/v1/roles \ -H "X-API-Key: $API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "attestation_minter", "description": "Can only mint attestations for specific issuers", "permissions": ["attestations:mint", "attestations:read", "issuers:read"], "constraints": { "issuer_ids": ["issuer-uuid-1", "issuer-uuid-2"] } }' ``` ### Resource-level constraints Custom roles support optional constraints that limit permissions to specific resources: ```json theme={null} { "name": "regional_auditor", "description": "Audit access scoped to EU issuers only", "permissions": ["attestations:read", "issuers:read", "audit:read"], "constraints": { "issuer_ids": ["eu-issuer-uuid-1", "eu-issuer-uuid-2"] } } ``` > [!NOTE] > > Resource-level constraints (such as limiting to specific issuers) are > available on Enterprise plans. ## API Key Scopes vs. User Roles Both API keys and users have permissions, but they work differently: | Aspect | API Key Scopes | User Roles | | - | - | - | | Assignment | Set at key creation, immutable | Can be changed anytime | | Audit Trail | Actions logged as API key ID | Actions logged as user email | | Multiple | One key = one set of scopes | User can have multiple roles | | Use Case | Server-to-server integration | Human users via UI/dashboard | ## Best Practices * **Least Privilege:** Grant only the permissions needed for each role * **Separate Duty:** Don't give one role both `attestations:mint` and `governance:approve` * **Regular Audits:** Review role assignments quarterly * **Use API Keys for Automation:** Don't share user credentials for scripts * **Document Custom Roles:** Keep a record of why custom roles were created ## Next Steps > **[Audit Logs](/security/audit)** > > Track all permission-related events. > **[Identity API](/api-reference/identity/orgs)** > > Manage users and roles programmatically. # Row-Level Security (RLS) Source: https://docs.truthlocks.com/security/rls Defense-in-depth tenant isolation at the database layer. Truthlocks uses Postgres Row-Level Security (RLS) as a defense-in-depth measure to enforce tenant isolation at the database layer. Even if application code has bugs, cross-tenant data access is prevented by the database itself. > [!NOTE] > > RLS is enforced in addition to application-level tenant filtering. Both layers > work together to ensure data isolation. ## How It Works ### Session Variable Each database request sets a session variable with the verified tenant ID: ```sql theme={null} SET LOCAL app.tenant_id = 'verified-tenant-uuid'; ``` ### Policy Definition RLS policies check that rows match the session tenant: ```sql theme={null} CREATE POLICY tenant_isolation ON issuers USING (tenant_id = current_setting('app.tenant_id')::uuid) WITH CHECK (tenant_id = current_setting('app.tenant_id')::uuid); ``` ### Tenant Identity Source The tenant ID is derived **only** from verified authentication context: * JWT claims (after signature verification) * API key lookup (after hash validation) * **Never** from client-provided headers like `X-Tenant-ID` ## Covered Tables RLS is enabled on all tenant-scoped tables: | Table | Tenant Column | Policy | | :- | :- | :- | | `issuers` | `tenant_id` | ✓ Enabled | | `issuer_keys` | `tenant_id` | ✓ Enabled | | `policies` | `tenant_id` | ✓ Enabled | | `tenant_api_keys` | `tenant_id` | ✓ Enabled | | `attestations` | `tenant_id` | ✓ Enabled | | `risk_signals` | `tenant_id` | ✓ Enabled | | `risk_event_sources` | `tenant_id` | ✓ Enabled | | `risk_decisions` | `tenant_id` | ✓ Enabled | | `fraud_cases` | `tenant_id` | ✓ Enabled | | `fraud_events` | `tenant_id` | ✓ Enabled | ## Fail-Closed Behavior If `app.tenant_id` is not set in the session: * **SELECT**: Returns zero rows (not an error) * **INSERT**: Fails with RLS policy violation * **UPDATE/DELETE**: Affects zero rows ## Verification Run the RLS isolation test suite: ```bash theme={null} make rls-check ``` ## Implementation Notes ### Connection Pooling When using connection pools, ensure that `SET LOCAL` is used within a transaction. ```go theme={null} // Go example with pgx tx, _ := pool.Begin(ctx) defer tx.Rollback(ctx) tx.Exec(ctx, "SET LOCAL app.tenant_id = $1", tenantID) // ... perform queries ... tx.Commit(ctx) ``` # SAML SSO Source: https://docs.truthlocks.com/security/saml-sso Configure SAML 2.0 single sign-on for your organization. Truthlocks supports native SAML 2.0 single sign-on so your team can authenticate through your existing identity provider (IdP). When SAML is configured, users are automatically routed to your IdP during login. > [!NOTE] > > SAML SSO is available on the **Business** plan and above. ## How it works **1. Configure your IdP** Register Truthlocks as a service provider (SP) in your identity provider. You need the SP Entity ID and Assertion Consumer Service (ACS) URL from the setup screen. **2. Add connection in Truthlocks** In the console, go to **Settings > SSO** and create a new SAML connection. Enter your IdP metadata URL or manually provide the IdP entity ID, SSO URL, and signing certificate. **3. Users sign in via IdP** Once active, users who visit the console login page are redirected to your IdP. After authenticating, they are returned to Truthlocks with a session. ## Service provider details Provide these values to your IdP when registering Truthlocks: | Field | Value | | - | - | | SP Entity ID | `urn:truthlocks:TENANT_ID` | | ACS URL | `https://console.truthlocks.com/api/auth/saml/acs` | | NameID format | `urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress` | | Binding | HTTP-POST | ## IdP configuration fields When creating a SAML connection in the console, you can configure your IdP in two ways: ### Option A: metadata URL Provide your IdP metadata URL and Truthlocks automatically fetches the entity ID, SSO URL, and signing certificate. ### Option B: manual configuration | Field | Description | | - | - | | IdP Entity ID | Your identity provider's unique identifier | | IdP SSO URL | The URL where Truthlocks sends SAML authentication requests | | IdP Certificate | The X.509 signing certificate from your IdP (PEM format) | ## Creating a connection via the API ```bash theme={null} curl -X POST https://api.truthlocks.com/v1/sso/connections \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "provider_type": "SAML", "idp_metadata_url": "https://idp.example.com/metadata", "role_mapping_mode": "GROUPS" }' ``` If you prefer manual configuration, omit `idp_metadata_url` and provide `idp_entity_id`, `idp_sso_url`, and `idp_certificate` instead. ## Role mapping Truthlocks maps IdP group assertions to internal roles during sign-in. Two modes are available: | Mode | Behavior | | - | - | | `STATIC` | All SAML users receive a fixed default role (e.g., `viewer`) | | `GROUPS` | IdP group names are mapped to Truthlocks roles (`admin`, `editor`, `auditor`) automatically | Set the mode when creating or updating the SSO connection. ## User provisioning When a user authenticates via SAML for the first time, Truthlocks automatically creates their account using attributes from the SAML assertion (email, first name, last name). This is called just-in-time (JIT) provisioning. For bulk user sync and deprovisioning, use [SCIM provisioning](/security/scim). ## Session details * Sessions last **12 hours** after SAML login. * Session cookies are `HttpOnly` and `SameSite=Lax`. * A 2-minute clock skew tolerance is applied when validating SAML assertions. ## Testing a connection After creating a SAML connection, test it before enabling for all users: ```bash theme={null} curl -X POST https://api.truthlocks.com/v1/sso/connections//test \ -H "Authorization: Bearer " ``` This validates that Truthlocks can reach your IdP and parse the metadata correctly. ## Disabling SSO To revert to standard email/password authentication: ```bash theme={null} curl -X POST https://api.truthlocks.com/v1/sso/connections//disable \ -H "Authorization: Bearer " ``` ## Related * [SCIM provisioning](/security/scim) — Automate user and group sync from your IdP. * [RBAC & permissions](/security/rbac) — Understand the roles that SAML users are mapped to. * [Authentication](/security/auth) — API key and JWT authentication methods. # SCIM provisioning Source: https://docs.truthlocks.com/security/scim Automate user and group lifecycle management with SCIM 2.0. Truthlocks supports SCIM 2.0 for automated user provisioning and group management. Connect your identity provider (Okta, Azure AD, OneLogin, etc.) to automatically create, update, and deactivate users in your Truthlocks tenant. > [!NOTE] > > SCIM provisioning is available on the **Business** plan and above. ## How it works **1. Generate a SCIM token** In the console, go to **Settings > SCIM** and generate a bearer token. This token authenticates your IdP's SCIM requests. **2. Configure your IdP** In your identity provider, set the SCIM base URL to `https://api.truthlocks.com/scim/v2` and paste the bearer token. **3. Sync users and groups** Your IdP pushes user creates, updates, and deactivations to Truthlocks automatically. Group membership changes update role assignments. ## SCIM base URL ```text theme={null} https://api.truthlocks.com/scim/v2 ``` All SCIM requests must include the bearer token in the `Authorization` header: ```bash theme={null} curl -X GET https://api.truthlocks.com/scim/v2/Users \ -H "Authorization: Bearer scim_your_token_here" ``` ## Supported operations ### Users | Operation | Method | Path | Description | | - | - | - | - | | List | GET | `/scim/v2/Users` | List users with optional filter | | Create | POST | `/scim/v2/Users` | Provision a new user | | Get | GET | `/scim/v2/Users/{id}` | Retrieve a user by SCIM ID | | Replace | PUT | `/scim/v2/Users/{id}` | Full user replacement | | Patch | PATCH | `/scim/v2/Users/{id}` | Partial update (e.g., deactivate) | | Delete | DELETE | `/scim/v2/Users/{id}` | Suspend the user | ### Groups | Operation | Method | Path | Description | | - | - | - | - | | List | GET | `/scim/v2/Groups` | List groups | | Create | POST | `/scim/v2/Groups` | Create a group mapping | | Get | GET | `/scim/v2/Groups/{id}` | Retrieve a group by SCIM ID | | Replace | PUT | `/scim/v2/Groups/{id}` | Replace group (re-maps role bindings) | | Patch | PATCH | `/scim/v2/Groups/{id}` | Add or remove members | | Delete | DELETE | `/scim/v2/Groups/{id}` | Delete group mapping | ### Discovery | Method | Path | Description | | - | - | - | | GET | `/scim/v2/ServiceProviderConfig` | Supported capabilities | | GET | `/scim/v2/Schemas` | Resource schemas | | GET | `/scim/v2/ResourceTypes` | Available resource types | ## Creating a user ```bash theme={null} curl -X POST https://api.truthlocks.com/scim/v2/Users \ -H "Authorization: Bearer scim_your_token_here" \ -H "Content-Type: application/json" \ -d '{ "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"], "userName": "jane@example.com", "name": { "givenName": "Jane", "familyName": "Smith" }, "emails": [{ "value": "jane@example.com", "primary": true }], "active": true }' ``` ## Deactivating a user IdPs like Okta and Azure AD send a PATCH request to deactivate users: ```bash theme={null} curl -X PATCH https://api.truthlocks.com/scim/v2/Users/{id} \ -H "Authorization: Bearer scim_your_token_here" \ -H "Content-Type: application/json" \ -d '{ "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"], "Operations": [{ "op": "replace", "path": "active", "value": false }] }' ``` Deactivated users lose access immediately but their data is retained. ## Managing SCIM tokens Generate and manage tokens through the management API: ```bash theme={null} # Generate a new token curl -X POST https://api.truthlocks.com/v1/scim/tokens \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "label": "Okta SCIM" }' # List tokens curl -X GET https://api.truthlocks.com/v1/scim/tokens \ -H "Authorization: Bearer " # Revoke a token curl -X DELETE https://api.truthlocks.com/v1/scim/tokens/ \ -H "Authorization: Bearer " ``` ## Activity log All SCIM operations are recorded in an activity log. View recent provisioning events: ```bash theme={null} curl -X GET https://api.truthlocks.com/v1/scim/activity \ -H "Authorization: Bearer " ``` Activity types include `USER_CREATED`, `USER_DEACTIVATED`, `USER_PATCHED`, `GROUP_CREATED`, `GROUP_UPDATED`, and `GROUP_DELETED`. ## Seat enforcement User creation respects your plan's seat limit. If the limit would be exceeded, the SCIM endpoint returns HTTP `402` and the user is not created. Upgrade your plan or remove inactive users to free seats. ## Filtering The SCIM `filter` query parameter lets your identity provider narrow list responses to specific users or groups. Truthlocks supports filtering on specific SCIM attributes using the operators below. ### Supported filter attributes | Attribute | Resource | Description | | - | - | - | | `userName` | Users | The user's login identifier (usually an email address) | | `displayName` | Users, Groups | The user's or group's display name | | `externalId` | Users, Groups | The unique identifier assigned by your identity provider | | `active` | Users | Whether the user account is active (`true` / `false`) | ### Supported operators | Operator | Meaning | Example | | - | - | - | | `eq` | Equals | `userName eq "jane@example.com"` | | `ne` | Not equals | `active ne false` | | `co` | Contains | `userName co "example.com"` | | `sw` | Starts with | `userName sw "jane"` | | `ew` | Ends with | `userName ew "@example.com"` | Combine operators using `and` / `or` for complex queries: ```bash theme={null} # Find active users whose username contains "example.com" curl -G https://api.truthlocks.com/scim/v2/Users \ -H "Authorization: Bearer scim_your_token_here" \ --data-urlencode 'filter=active eq true and userName co "example.com"' # Find users starting with "jane" or "john" curl -G https://api.truthlocks.com/scim/v2/Users \ -H "Authorization: Bearer scim_your_token_here" \ --data-urlencode 'filter=userName sw "jane" or userName sw "john"' # Look up a user by their IdP-assigned external ID curl -G https://api.truthlocks.com/scim/v2/Users \ -H "Authorization: Bearer scim_your_token_here" \ --data-urlencode 'filter=externalId eq "00u1a2b3c4d5e6f7g8h9"' # Find a user by display name curl -G https://api.truthlocks.com/scim/v2/Users \ -H "Authorization: Bearer scim_your_token_here" \ --data-urlencode 'filter=displayName eq "Jane Smith"' ``` > [!NOTE] > > Filtered results are capped at 200 items per response. If your IdP syncs more than 200 users or groups, it should paginate using the `startIndex` and `count` parameters alongside the filter. ### Common IdP filter patterns Most identity providers send filters automatically during sync. Here are the patterns that Truthlocks handles: | IdP | Typical filter sent | | - | - | | Okta | `userName eq "user@example.com"` | | Azure AD | `userName eq "user@example.com"`, `displayName co "Smith"`, or `externalId eq "id"` | | OneLogin | `userName sw "user"` or `externalId eq "id"` | If your IdP sends a filter using any of the supported attributes and operators listed above, Truthlocks processes it correctly. You do not need to configure anything on the Truthlocks side. ## Supported capabilities | Capability | Supported | | - | - | | Patch | Yes | | Bulk | No | | Filter | Yes — `eq`, `ne`, `co`, `sw`, `ew` on `userName`, `displayName`, `externalId`, `active` with `and` / `or` (max 200 results) | | Sort | No | | Change password | No | | ETag | No | ## Related * [SAML SSO](/security/saml-sso) — Authenticate users through your IdP. * [RBAC & permissions](/security/rbac) — Roles assigned to provisioned users. * [Audit logs](/security/audit) — Track all access and provisioning events. # Support access sessions Source: https://docs.truthlocks.com/security/support-access How Truthlocks customer support accesses your tenant with time-limited, scoped impersonation sessions. When you contact Truthlocks support and troubleshooting requires access to your tenant, support staff use **impersonation sessions** — time-limited, scope-restricted sessions that are fully recorded in your audit log. ## How it works **1. Support creates a session** A support staff member creates an impersonation session specifying your tenant, the required permission scopes, a TTL, and a reason for access. Sessions can optionally be scoped to a specific organization within your tenant. **2. Session is time-limited** Every session has a configurable time-to-live (TTL) between 1 and 60 minutes (defaults to 15 minutes). When the TTL expires, access is revoked immediately — no manual action required. **3. Actions are recorded** Every HTTP request the support staff member makes during the session is recorded in a dedicated access log with the method, path, status code, and request ID. These events also appear in your tenant's [audit log](/security/audit). ## Session properties | Property | Description | | :- | :- | | **Tenant** | The tenant the session grants access to. | | **Organization** | *(optional)* A specific organization within the tenant. When set, access is restricted to that organization's data only. | | **Scopes** | The permissions granted for the session. Defaults to `read_only` if none are specified. | | **TTL** | Time-to-live in minutes (1–60, defaults to 15). | | **Reason** | A human-readable explanation of why the session was created (minimum 10 characters). | | **Status** | `ACTIVE` (in use), `EXPIRED` (TTL reached), or `REVOKED` (manually ended). | | **IP address** | The IP address of the support staff member who created the session. | | **User-Agent** | The browser or client used by support staff. | | **Issued at** | When the session was created. | | **Expires at** | When the session automatically expires, based on the TTL. | ## Session lifecycle * **Active** — the session is in use and the support staff member has access to the granted scopes. * **Expired** — the TTL has been reached and access is automatically revoked. * **Revoked** — a platform administrator ended the session early. The administrator's identity and an optional revocation reason are recorded. ## Reviewing support activity ### Audit log All support session activity appears in your tenant's [audit log](/security/audit). Filter by the `support_session` event category to see exactly what was accessed and when. ```bash theme={null} curl "https://api.truthlocks.com/v1/audit?category=support_session" \ -H "X-API-Key: tl_live_..." ``` Each audit event includes the session ID, the staff member's identity, the action performed, and a timestamp. ### Per-session access logs You can also retrieve a detailed access log for a specific session. Each entry records the HTTP method, request path, response status code, and a unique request ID. ```json theme={null} [ { "method": "GET", "path": "/v1/attestations", "status_code": 200, "request_id": "req_abc123", "timestamp": "2026-03-26T14:30:00Z" } ] ``` ## Security controls > **Scoped access** > > Sessions are restricted to specific permission scopes and, optionally, a > single organization. Support cannot access resources outside the granted > scopes. > **Time-limited** > > Every session expires automatically based on its TTL (1–60 minutes). > There are no permanent support access grants. > **Full audit trail** > > Every HTTP request is recorded in the session's access log with the > staff member's IP address and User-Agent. > **Revocable** > > Active sessions can be revoked at any time by a platform administrator, > with an optional reason. ## Related > **[Audit logs](/security/audit)** > > View and export your tenant's audit events. > **[RBAC](/security/rbac)** > > Understand roles and permission scopes. # DID & JWKS discovery Source: https://docs.truthlocks.com/specification/did-jwks Resolve issuer identities and public keys using standard discovery protocols. Truthlocks provides public endpoints for resolving issuer identities using W3C Decentralized Identifiers (DIDs) and retrieving signing keys via JSON Web Key Sets (JWKS). These endpoints enable standards-based key verification without proprietary integrations. ## DID resolution Every issuer has a DID in the format `did:truthlock:{issuer_id}` that resolves to a W3C DID Document containing their public key material and service endpoints. DIDs are automatically assigned when an issuer is created. ### Endpoint ```text theme={null} GET /v1/public/did/{did} ``` No authentication required. Responses are cached for 1 hour. ### Example request ```bash theme={null} curl https://api.truthlocks.com/v1/public/did/did:truthlock:iss_p4q5r6 ``` ### Example response ```json theme={null} { "@context": [ "https://www.w3.org/ns/did/v1", "https://w3id.org/security/suites/jws-2020/v1" ], "id": "did:truthlock:iss_p4q5r6", "controller": "did:truthlock:iss_p4q5r6", "verificationMethod": [ { "id": "did:truthlock:iss_p4q5r6#key-1", "type": "Ed25519VerificationKey2020", "controller": "did:truthlock:iss_p4q5r6", "publicKeyJwk": { "kty": "OKP", "crv": "Ed25519", "x": "base64url-encoded-public-key", "kid": "key-1", "alg": "ed25519" } } ], "authentication": ["did:truthlock:iss_p4q5r6#key-1"], "assertionMethod": ["did:truthlock:iss_p4q5r6#key-1"], "service": [ { "id": "did:truthlock:iss_p4q5r6#verification", "type": "TruthlockVerification", "serviceEndpoint": "https://api.truthlocks.com/v1/verify" }, { "id": "did:truthlock:iss_p4q5r6#portfolio", "type": "TruthlockPortfolio", "serviceEndpoint": "https://verify.truthlocks.com/portfolio" } ] } ``` The response uses `Content-Type: application/did+json`. ### Verification method types The key type in the DID Document depends on the issuer's signing algorithm: | Algorithm | Verification type | JWK key type | Curve | | - | - | - | - | | Ed25519 | `Ed25519VerificationKey2020` | `OKP` | `Ed25519` | | ES256 | `JsonWebKey2020` | `EC` | `P-256` | | RS256 | `JsonWebKey2020` | `RSA` | — | ## JWKS endpoint Retrieve all active public keys for an issuer as a standard JSON Web Key Set. ### Endpoint ```text theme={null} GET /v1/public/issuers/{issuer_id}/jwks.json ``` No authentication required. Responses are cached for 1 hour. ### Example request ```bash theme={null} curl https://api.truthlocks.com/v1/public/issuers/iss_p4q5r6/jwks.json ``` ### Example response ```json theme={null} { "keys": [ { "kty": "OKP", "crv": "Ed25519", "x": "base64url-encoded-public-key", "kid": "key-1", "alg": "ed25519" } ] } ``` ## When to use each endpoint | Use case | Endpoint | | - | - | | Verify a proof bundle offline using the `issuer_did` field | DID resolution | | Validate JWT signatures from Truthlocks services | JWKS | | Build integrations that follow W3C Verifiable Credentials standards | DID resolution | | Integrate with existing OIDC/JWT infrastructure | JWKS | ## Using DIDs in proof bundles The `issuer_certificate.issuer_did` field in a [proof bundle](/specification/proof-bundle) contains the issuer's DID. You can resolve it to retrieve the public key and independently verify the attestation signature without relying on Truthlocks infrastructure. ## Related * [Proof bundle format](/specification/proof-bundle) — The cryptographic proof format that references issuer DIDs. * [Issuer keys API](/api-reference/issuers/keys) — Manage issuer signing keys. # Proof Bundle Format Source: https://docs.truthlocks.com/specification/proof-bundle Specification for the cryptographic Truthlocks Proof Bundle format version 1.0. A **Truthlocks Proof Bundle** carries evidence for supported cryptographic checks of a record. Offline verification requires the corresponding payload, supported format and independently trusted issuer and log keys. It does not establish current revocation status, issuer authority, factual truth or whether a real-world action occurred. SPECIFICATION v1.0 ## 1. Overview A Truthlocks Proof Bundle is a portable evidence document. Use the format and verifier documented for the endpoint that produced it. CBOR support is listed below as a future extension, not a guarantee for current exports. Evidence can include attestation data, key references, and transparency-log proofs. Verify the signature and log inclusion separately; absent evidence must not be reported as a passed check. Never trust a public key solely because it is included in the bundle: establish the authorized key through a trusted channel. The schema below is a reference description; match the actual export version and its signed-byte contract before implementing a verifier. ## 2. Bundle Structure Proof bundles are serialized as JSON objects and follow this schema: ```json theme={null} { "header": { "version": "1.0", "bundle_id": "bun_a1b2c3d4...", "generated_at": "2026-03-12T14:30:00Z", "format": "json", "tenant_id": "ten_x9y8z7..." }, "attestation": { "id": "att_k7x2m9...", "type": "content_protection", "subject": "main.ts", "subject_type": "file", "content_hash": "sha256:a1b2c3d4e5f6...", "metadata": { "title": "My Project", "category": "code", "file_size": 4096 }, "issued_at": "2026-03-12T14:28:00Z", "issuer_id": "iss_p4q5r6...", "issuer_key_id": "key_m1n2o3...", "signature": "base64url-encoded-signature", "signature_format": "Ed25519", "status": "active" }, "proofs": [ { "log_id": "log_main", "tree_size": 42857, "leaf_index": 42856, "leaf_hash": "sha256:...", "inclusion_proof": ["sha256:...", "sha256:...", "..."], "root_hash": "sha256:...", "timestamp": "2026-03-12T14:28:01Z" } ], "issuer_certificate": { "issuer_id": "iss_p4q5r6...", "issuer_did": "did:truthlock:iss_p4q5r6...", "key_id": "key_m1n2o3...", "algorithm": "Ed25519", "public_key_der": "base64-encoded-public-key", "valid_from": "2026-01-01T00:00:00Z", "trust_anchor": "truthlocks-root-2026" }, "bundle_hash_b64url": "base64url-encoded-sha256-of-bundle", "bundle_signature": { "key_id": "truthlocks-signing-key-2026", "algorithm": "Ed25519", "value": "base64-encoded-bundle-signature" } } ``` ## 3. Field Definitions ### 3.1 Header | Field | Type | Required | Description | | :- | :- | :- | :- | | `version` | string | Yes | Bundle format version (currently "1.0") | | `bundle_id` | string | Yes | Unique identifier for this bundle | | `generated_at` | datetime | Yes | ISO 8601 timestamp of bundle generation | | `format` | string | Yes | Encoding format: "json" or "cbor" | | `tenant_id` | string | Yes | Tenant that owns the attestation | ### 3.1.1 Bundle integrity hash | Field | Type | Required | Description | | :- | :- | :- | :- | | `bundle_hash_b64url` | string | Yes | Base64url-encoded SHA-256 hash of all bundle fields (excluding `bundle_hash_b64url` and `bundle_signature`). Used for tamper detection — any modification to bundle content invalidates this hash. | ### 3.2 Attestation | Field | Type | Required | Description | | :- | :- | :- | :- | | `id` | string | Yes | Attestation identifier | | `type` | string | Yes | Attestation type (e.g. content\_protection, identity.kyc) | | `subject` | string | Yes | Subject of the attestation (filename, person, etc.) | | `subject_type` | string | No | Type hint for the subject (file, person, org) | | `content_hash` | string | Yes | SHA-256 hash of the attested content (prefixed sha256:) | | `document_hash` | string | No | Pre-computed SHA-256 hash passed at mint time. When provided, the platform uses this value instead of computing the hash internally. | | `metadata` | object | No | Additional metadata about the attestation | | `issued_at` | datetime | Yes | When the attestation was minted | | `valid_from` | datetime | No | Start of validity period | | `valid_until` | datetime | No | End of validity period (null = no expiry) | | `issuer_id` | string | Yes | ID of the issuing entity | | `issuer_key_id` | string | Yes | Key ID used to sign the attestation | | `signature` | string | Yes | Base64url-encoded signature over the attestation payload | | `signature_format` | string | Yes | Algorithm used: Ed25519, ES256, RS256 | | `status` | string | Yes | Status snapshot at export; refresh for current acceptance | ### 3.3 Proofs (Transparency Log) | Field | Type | Description | | :- | :- | :- | | `log_id` | string | Identifier of the transparency log | | `tree_size` | integer | Merkle tree size at the time of inclusion | | `leaf_index` | integer | Position of this entry in the tree | | `leaf_hash` | string | SHA-256 hash of the leaf node | | `inclusion_proof` | string\[] | Ordered list of sibling hashes forming the inclusion proof path | | `root_hash` | string | Signed tree head root hash at time of inclusion | | `timestamp` | datetime | When the entry was appended to the log | ### 3.4 Issuer Certificate | Field | Type | Description | | :- | :- | :- | | `issuer_id` | string | Issuer UUID | | `issuer_did` | string | W3C Decentralized Identifier (did:truthlock:...) | | `key_id` | string | Key identifier | | `algorithm` | string | Key algorithm: Ed25519, ES256, RS256 | | `public_key_der` | string | Base64-encoded public key in DER format | | `valid_from` | datetime | Key validity start | | `valid_until` | datetime | Key validity end (null = no expiry) | | `trust_anchor` | string | Reference to root trust anchor | ## 4. Verification Algorithm To verify a Truthlocks Proof Bundle, execute the following steps in order. If any step fails, the bundle is invalid. ### Step 1: Validate bundle integrity Compute the SHA-256 hash of all bundle fields excluding `bundle_hash_b64url` and `bundle_signature`. Base64url-decode the `bundle_hash_b64url` value and compare it to your computed hash. If they do not match, the bundle has been tampered with. ### Step 2: Verify attestation signature Using the public key from `issuer_certificate.public_key_der` and the algorithm specified in `attestation.signature_format`, verify `attestation.signature` against the canonical attestation payload (all attestation fields except `signature` and `status`). ### Step 3: Verify content hash If you have the original file, compute its SHA-256 hash and compare it to `attestation.content_hash`. This confirms the file has not been modified since attestation. If a `document_hash` value is present, you can also compare it against your computed hash. The `document_hash` is a pre-computed SHA-256 hex hash that the minter passed at mint time, providing an additional integrity check independent of the payload encoding. ### Step 4: Verify transparency log inclusion For each entry in `proofs`, verify the Merkle inclusion proof. Starting from `leaf_hash` at position `leaf_index`, recompute the root by hashing with each sibling in `inclusion_proof`. The result must match `root_hash`. ### Step 5: Verify key validity Confirm that `issuer_certificate.valid_from` ≤ `attestation.issued_at` ≤ `issuer_certificate.valid_until` (if present). ## 5. Supported Algorithms | Algorithm | Key Type | Use | | :- | :- | :- | | `Ed25519` | OKP (Curve25519) | Default for consumer issuers. Fast, compact signatures. | | `ES256` | EC (P-256) | ECDSA with SHA-256. FIPS-compliant. | | `RS256` | RSA (2048+) | RSA with SHA-256. Legacy compatibility. | ## 6. Verification Tools Proof bundles can be verified using any of these methods: * **CLI**: `truthlock verify -b bundle.json -f original-file --trusted-log-key "$TRUTHLOCKS_LOG_PUBLIC_KEY" --trusted-issuer-key "$TRUTHLOCKS_ISSUER_PUBLIC_KEY"`. Pin both public keys independently of the bundle. Offline checks do not establish current revocation status. * **Web**: Upload at `verify.truthlocks.com/proof/[id]` * **SDK**: `client.verify.verifyBundle(bundleJson, fileBuffer)` * **Manual**: Follow the verification algorithm above with any Ed25519/ECDSA library ## 7. Extension Points The `metadata` field in the attestation object is extensible. Custom schemas can include additional fields without breaking verification. The core verification algorithm only depends on `content_hash`, `signature`, and the transparency log proofs. Future format versions may introduce: * CBOR encoding for compact binary representation * Multi-attestation bundles (batch verification) * Cross-log consistency proofs * Revocation status proofs (embedded) ## 8. Design Principles * **Self-contained**: No network access required for verification * **Trust-minimized**: Verifiable even if Truthlocks ceases to operate * **Forward-compatible**: Unknown fields are ignored by older verifiers * **Deterministic**: Canonical JSON encoding ensures consistent hashing * **Open**: Uses standard cryptographic primitives (no proprietary formats) # Compliance evidence Source: https://docs.truthlocks.com/trust/compliance Assess compliance using current evidence and the actual deployment. Truthlocks can record claims, approvals, and audit evidence. These features are not themselves a SOC 2 report, regulatory certification, or a legal determination of compliance. ## Evidence to obtain Before relying on a compliance claim, obtain the current assessment or agreement and confirm its scope, dates, covered services, deployment, and exceptions. This documentation does not establish an annual independent penetration test, SOC 2 Type II certification, or blanket GDPR/CCPA compliance. ## Data handling Confirm retention, backup recovery, deletion behavior, subprocessors, and storage locations for the actual workspace. A country or region preference does not establish exclusive regional processing. See [data location](/security/data-residency). ## Exports and reports [Audit exports](/api-reference/audit/export) contain recorded events. [MAIP reports](/api-reference/machine-identity/compliance/reports) aggregate recorded checks. Neither independently certifies controls. Review source evidence and applicable requirements with the responsible reviewer. # Privacy Policy Summary Source: https://docs.truthlocks.com/trust/privacy A summary of how Truthlocks handles and protects your data. Your privacy is paramount. This summary outlines how we handle data at Truthlocks. For the full legal text, please visit our [Terms of Service and Privacy Policy](/policy). ### Data We Collect * **Account Information**: Email, name (for admin access). * **Verification Data**: Evidence provided by end-users (encrypted). * **Usage Logs**: API request metadata (access logs). ### How We Use Data We use data solely to provide the Identity Verification service. **We do not sell data to advertisers or third parties.** ### Data processors The current deployment uses Google Cloud infrastructure and Zoho transactional email. Billing and optional AI features can involve additional providers. Request the current processor list and processing locations for your workspace; historical AWS and Postmark listings do not describe the recovery deployment. ### Your Rights You have the right to access, correct, export, or delete your personal data at any time. These actions can be performed directly via the Truthlocks Console or API. # Security Architecture Source: https://docs.truthlocks.com/trust/security Implemented controls and how to assess their limits. Truthlocks uses authenticated workspace context, application authorization, database isolation, and cryptographic verification for distinct purposes. ## Infrastructure The current recovery deployment uses Google Cloud. Older claims that all infrastructure runs on AWS, or that AWS Shield protects this deployment, are obsolete. Infrastructure encryption and access controls must be assessed against the deployed services and configuration. ## Application controls * Workspace identity comes from authenticated credentials. Caller-supplied tenant headers do not select another workspace. * Database row-level security and application checks are used to restrict tenant data access. Their effectiveness depends on correct policies, roles, and query paths. * User roles and service-key permissions are different. An API key does not automatically provide a user's role or reviewer identity. * MFA is available in supported sign-in flows; its availability is not evidence that every account has enrolled or that every administrative path enforces it. ## Cryptographic evidence A valid signature and inclusion proof establish specific integrity properties. They do not establish the truth of the signed claims. Some MAIP tracking receipts currently contain system markers rather than cryptographic signatures; consult the operation reference before using a receipt as proof. ## Assurance evidence Do not infer an independent security audit, penetration-test schedule, certification, or review of every change from this page. Request current evidence covering the services and deployment you intend to use. See [data location](/security/data-residency) and [compliance](/trust/compliance).