Authorization

Include `requirements` and `options` with authorize requests to produce a single, auditable decision.

Requirements

Requirements are the `requirements` block you include with an authorize request that tells the system how to convert claim verification results into a single, auditable decision (allow, deny, or needs_review).

decision_mode

string

Default: strict

Decision mode: "strict" denies when thresholds fail; "balanced" favors needs_review for borderline cases; "audit" records the outcome without blocking.

min_coverage

number

Default: 0.85

Minimum fractional coverage (0–1) required for a claim to be considered supported (requirements.min_coverage). Range: 0.0–1.0.

citations

string

Default: required

Whether citations are required for a claim to be treated as supported: "required" or "optional" (requirements.citations).

Send `requirements` and `options` with authorize / authorize-answer requests.

Options

Configure authorization behavior with these fields.

deny_if_any_unsupported

boolean

Default: false

If true, any unsupported claim will cause a deny decision rather than routing the request for review.

evidence_limit

number

Default: 5

Maximum number of evidence passages to include per claim (processing limit).

semantic_verify

boolean

Default: false

Enable hybrid semantic verification (opt-in): when true, embedding-based retrieval + NLI entailment will be used as a fallback when deterministic citations are missing.

top_k_semantic

number

Default: 8

Number of candidate passages retrieved via embeddings before running NLI (tunable).

entailment_threshold

number

Default: 0.85

NLI entailment confidence threshold (0–1) used to accept a passage as supporting evidence.

semantic_verify_background

boolean

Default: false

Enqueue semantic verification to run asynchronously (opt-in). The request returns immediately and, on success, the response includes a background_job_id you can poll via GET /v1/jobs/{job_id} or subscribe to SSE job updates.

Examples

Each example shows a minimal authorize request and the Decision Artifact response.

Note: Example decision artifacts show full details (claims, citations). Responses are compact-by-default; include "response": { "mode": "verbose" } in your request to receive per-claim details.

Strict — deny on missing evidence

Request

{
  "claims": [
    {
      "text": "Customer X consented to sharing data."
    }
  ],
  "requirements": {
    "decision_mode": "strict"
  },
  "options": {
    "evidence_limit": 5,
    "deny_if_any_unsupported": false
  }
}

Response (Decision Artifact)

Compact (default response)

{
  "decision": "deny",
  "coverage_score": 0,
  "evaluated_at": "2026-01-09T12:00:00Z",
  "request_id": "req_strict_001",
  "request_hash": "sha256:strict000",
  "metrics": {
    "latency_ms": 120,
    "claims_total": 1,
    "claims_supported": 0,
    "sources_total": 0
  }
}

Permissive — needs_review for borderline support

Request

{
  "claims": [
    {
      "text": "We retain logs for 180 days."
    }
  ],
  "requirements": {
    "decision_mode": "balanced"
  },
  "options": {
    "evidence_limit": 5,
    "deny_if_any_unsupported": false
  }
}

Response (Decision Artifact)

Compact (default response)

{
  "decision": "needs_review",
  "coverage_score": 0.5,
  "evaluated_at": "2026-01-09T12:05:00Z",
  "request_id": "req_perm_002",
  "request_hash": "sha256:perm111",
  "metrics": {
    "latency_ms": 140,
    "claims_total": 1,
    "claims_supported": 0,
    "sources_total": 1
  }
}

Audit-only — record outcomes without blocking

Request

{
  "claims": [
    {
      "text": "We encrypt data at rest."
    }
  ],
  "requirements": {
    "decision_mode": "audit"
  },
  "options": {
    "evidence_limit": 5,
    "deny_if_any_unsupported": false
  }
}

Response (Decision Artifact)

Compact (default response)

{
  "decision": "allow",
  "coverage_score": 1,
  "evaluated_at": "2026-01-09T12:10:00Z",
  "request_id": "req_audit_003",
  "request_hash": "sha256:audit222",
  "metrics": {
    "latency_ms": 90,
    "claims_total": 1,
    "claims_supported": 1,
    "sources_total": 1
  }
}

Deny — no evidence

Request

POST /v2/authorize
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "action": { "type": "share_data", "params": { "user_id": "customer_x", "recipient": "data_broker" } },
  "claims": [ { "text": "Customer X consented to sharing data." } ],
  "sources": [],
  "requirements": { "min_coverage": 0.85, "decision_mode": "strict" },
  "options": { "deny_if_any_unsupported": true }
}

Response (Decision Artifact)

Compact (default response)

{
  "decision": "deny",
  "coverage_score": 0,
  "evaluated_at": "2026-01-09T12:15:00Z",
  "request_id": "req_deny_004",
  "request_hash": "sha256:deny333",
  "metrics": {
    "latency_ms": 100,
    "claims_total": 1,
    "claims_supported": 0,
    "sources_total": 0
  }
}

Enforcement

Allow

Proceed with the action. Log the decision and the included reasons for auditing.

Deny

Do not perform the action. Return the decision and reasons to the caller and record the event for review.

Needs review

Pause the action and surface the reasons to a reviewer; attach the Decision Artifact so the reviewer can act quickly.

FAQ

Do requirements fetch evidence?

No — provide evidence or citations in the request; requirements only evaluate what you send.

When should I use permissive mode?

Use permissive when you want borderline cases routed for human review instead of blocked.

How do I enforce the decision?

Apply the decision locally: execute on allow, block on deny, and queue or notify reviewers on needs_review.

View API Reference