> ## 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.

# Evaluate policy

> 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>

<Info>
  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).
</Info>

### Parameters

<ParamField body="action" type="string" required>
  The policy category to evaluate: `MINT`, `VERIFY`, or `BUNDLE_EXPORT`.
</ParamField>

<ParamField body="target_type" type="string" required>
  The binding target type: `ISSUER`, `VERIFICATION_PROFILE`, or `TENANT_DEFAULT`.
</ParamField>

<ParamField body="target_id" type="string">
  UUID of the specific target. Omit for `TENANT_DEFAULT` to evaluate tenant-wide policies.
</ParamField>

<ParamField body="input" type="object" required>
  Key-value pairs representing the request context. Supports dot-notation for nested fields (e.g., `key.age_days`).

  Common fields include `jurisdiction`, `trust_tier`, `status`, `risk_rating`, `assurance_level`, `key.age_days`, and `key.status`. See the [available fields reference](/guides/issuance-policies#available-fields) for the full list.
</ParamField>

### 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). |


## OpenAPI

````yaml mint-openapi.yaml POST /v1/policies/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 <jwt>` 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/policies/evaluate:
    post:
      tags:
        - Policies
      summary: Evaluate policies
      description: Evaluates all active policies against a specific action and context.
      operationId: policies.evaluate
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - category
                - context
              properties:
                category:
                  type: string
                  enum:
                    - MINT
                    - VERIFY
                    - BUNDLE_EXPORT
                context:
                  type: object
                  description: >-
                    Evaluation context (e.g. issuer details, attestation
                    metadata)
      responses:
        '200':
          description: Evaluation result
          content:
            application/json:
              schema:
                type: object
                properties:
                  decision:
                    type: string
                    enum:
                      - ALLOW
                      - DENY
                  matched_policy:
                    type: string
                    nullable: true
                  matched_rule:
                    type: string
                    nullable: true
                  reason:
                    type: string
        '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

````