> ## Documentation Index
> Fetch the complete documentation index at: https://docs.truthlocks.com/llms.txt
> Use this file to discover all available pages before exploring further.
# 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 |
## Request
Signal type: `velocity`, `ato`, `deepfake`, `impersonation`, `geo_anomaly`, `behavior`, `device_fingerprint`
Subject identifier.
Risk score (0–100).
Defaults to `user`.
If `true`, mints a `fraud_decision_receipt` after evaluation. Requires `issuer_id` and `kid`.
Issuer UUID for receipt minting.
Key ID for receipt signing.
## Response
`allow` | `challenge` | `block` | `review`
UUID of the risk decision record.
UUID of the ingested risk signal.
UUID of the matching policy rule (if any).
UUID of the minted receipt (only if `mint_receipt: true` and succeeded).
## OpenAPI
````yaml mint-openapi.yaml POST /v1/risk/evaluate
openapi: 3.0.3
info:
title: Truthlocks API
description: >
Truthlocks is a universal verification infrastructure for documents,
credentials, and digital assets.
This specification defines the canonical API for interacting with Truthlocks
services.
## Base URLs
- **Production**: `https://api.truthlocks.com`
- **Sandbox**: `https://sandbox-api.truthlocks.com`
## Authentication
- **API Keys**: Use `X-API-Key` header for machine-to-machine operations
- **Bearer Tokens**: Use `Authorization: Bearer ` for user-initiated
operations
## Tenant Identity
In production, tenant identity is derived from the authenticated context
(API key or JWT).
The `X-Tenant-ID` header is ignored in production to prevent spoofing.
version: 1.0.0
contact:
name: Truthlocks Support
url: https://truthlocks.com/support
email: support@truthlocks.com
servers:
- url: https://api.truthlocks.com
description: Production API
- url: https://sandbox-api.truthlocks.com
description: Sandbox Environment
security:
- APIKey: []
tags:
- name: Authentication
description: API key and token management
- name: Issuers
description: Issuer registration and trust management
- name: Keys
description: Cryptographic key management for issuers
- name: Attestations
description: Attestation lifecycle (mint, revoke, supersede)
- name: Verification
description: Attestation verification and proof bundles
- name: Governance
description: Issuer governance workflows (admin only)
- name: Identity
description: Organization, user, and role management
- name: Audit
description: Audit event queries
- name: Platform
description: Platform administration (super admin only)
- name: Platform Review
description: Staff review workflows for issuer applications
- name: Tenant Console
description: Tenant profile and lifecycle endpoints
- name: Health
description: Service health and readiness endpoints
- name: Risk
description: Risk signal ingestion and fraud detection
- name: Risk Enforcement
description: Risk enforcement actions — block, challenge, quarantine, and configuration
- name: Billing
description: Billing, subscription, and addon management
- name: Machine Identity
description: >-
Machine Agent Identity Protocol (MAIP) — agent registration, sessions,
trust, witness, compliance, orchestration, and observability
externalDocs:
description: Transparency read-only API (separate service spec)
url: >-
https://github.com/truthlocks/truthlock/blob/main/docs/transparency/openapi.yaml
paths:
/v1/risk/evaluate:
post:
tags:
- Risk
summary: Risk evaluate
description: >-
Unified risk evaluation. Ingests a signal, evaluates against policies,
creates a signed risk decision.
operationId: risk.evaluate
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- signal_type
- subject_id
- risk_score
properties:
signal_type:
type: string
enum:
- velocity
- ato
- deepfake
- impersonation
- geo_anomaly
- behavior
- device_fingerprint
subject_id:
type: string
risk_score:
type: integer
minimum: 0
maximum: 100
subject_type:
type: string
default: user
mint_receipt:
type: boolean
issuer_id:
type: string
kid:
type: string
responses:
'200':
description: Risk decision
content:
application/json:
schema:
type: object
properties:
decision_id:
type: string
signal_id:
type: string
decision:
type: string
enum:
- allow
- challenge
- block
- review
policy_id:
type: string
nullable: true
receipt_id:
type: string
nullable: true
'401':
description: Authentication required
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
security:
- APIKey: []
components:
schemas:
ErrorEnvelope:
type: object
required:
- code
- message
- http_status
properties:
code:
type: string
description: Machine-readable error code
enum:
- AUTH_REQUIRED
- AUTH_INVALID
- PERMISSION_DENIED
- TENANT_IDENTITY_UNVERIFIED
- NOT_FOUND
- VALIDATION_ERROR
- CONFLICT
- PAYLOAD_TOO_LARGE
- RATE_LIMIT_EXCEEDED
- QUOTA_EXCEEDED
- SERVICE_UNAVAILABLE
- INTERNAL_ERROR
message:
type: string
description: Human-readable error message
http_status:
type: integer
description: HTTP status code
retry_after_ms:
type: integer
description: Milliseconds to wait before retrying (for rate limits)
details:
type: object
description: Additional error context
example:
code: AUTH_REQUIRED
message: Authentication required
http_status: 401
securitySchemes:
APIKey:
type: apiKey
in: header
name: X-API-Key
description: API key for machine-to-machine authentication
````