---
title: "Evaluate a typed agent action against the active tenant policy"
method: POST
path: "/v1/actions/authorize"
tags: ["Actions"]
---

# Evaluate a typed agent action against the active tenant policy

`POST /v1/actions/authorize`

## Request

- Base URL: `https://api.thrd.email`
- URL: `https://api.thrd.email/v1/actions/authorize`
- Auth: HTTP bearer

Requires bearer scope actions:authorize. Tenant, environment, trusted facts and executor principal are resolved only by the server. The request is idempotent and persists proposal, decision, polling events, metrics and integrity-linked receipts atomically.

## Request body

- object
  - `action_id` string, required: Caller action identity. It is not the server proposal ID.
  - `schema_version` '1.0', required
  - `agent_id` string, uuid, required
  - `source` object, required
    - `type` 'email', required
    - `message_id` string, uuid, required
    - `envelope_id` string, uuid
  - `action` object, required
    - `type` string, required
    - `arguments` object, required: Action-catalog validated JSON object, capped at 16384 UTF-8 bytes. Authority fields such as tenant, environment and executor IDs are forbidden at any depth.
  - `runtime` object, required
    - `framework` string
    - `tool_name` string, required
    - `tool_version` string
    - `execution_target` string: Optional requested registered target. The executor principal ID is always resolved server-side.
  - `idempotency_key` string, required: Unique per tenant, agent and environment. Same payload returns the persisted graph; changed payload returns 409.

## Response `200`

Persisted deterministic decision. Shadow and enforce responses are disjoint; review/deny/shadow never return a capability bearer.

- union
  - object
    - `action_proposal_id` string, uuid, required
    - `decision_id` string, uuid, required
    - `receipt_id` string, uuid, required
    - `action_hash` string, required
    - `policy_hash` string, required
    - `decision_context_hash` string, required
    - `mode` 'enforce', required
    - `enforcement_applied` true, required
    - `decision` 'allow' | 'review' | 'deny', required
    - `reason_codes` string[], required
    - `matched_rule_ids` string[], required
    - `risk_summary` object, required
      - `maximum_severity` 'none' | 'low' | 'medium' | 'high' | 'critical', required
      - `signal_codes` string[], required
    - `trace_id` string, uuid, required
    - `idempotent_replay` boolean, required
    - `capability` union
      - object
        - `status` 'feature_disabled', required
      - object
        - `capability_id` string, uuid, required
        - `status` 'issued', required
        - `token` string: Compact single-use JWS. Present only for the first three identical deliveries inside 60 seconds; never persisted as plaintext.
        - `expires_at` string, date-time, required
        - `delivery_count` integer, required
        - `receipt_id` string, uuid
      - object
        - `capability_id` string, uuid, required
        - `status` 'redeemed' | 'expired' | 'revoked', required
        - `expires_at` string, date-time, required
        - `delivery_count` integer, required
    - `approval` union
      - object
        - `status` 'feature_disabled', required
      - object
        - `approval_id` string, uuid, required
        - `status` 'pending', required
        - `expires_at` string, date-time, required
        - `receipt_id` string, uuid, required
      - object
        - `approval_id` string, uuid, required
        - `status` 'approved' | 'denied' | 'modified' | 'expired' | 'canceled' | 'capability_issued' | 'executed' | 'execution_failed', required
        - `expires_at` string, date-time, required
        - `completed_at` string, date-time, required
        - `receipt_id` string, uuid, required
  - object
    - `action_proposal_id` string, uuid, required
    - `decision_id` string, uuid, required
    - `receipt_id` string, uuid, required
    - `action_hash` string, required
    - `policy_hash` string, required
    - `decision_context_hash` string, required
    - `mode` 'shadow', required
    - `enforcement_applied` false, required
    - `would_decision` 'allow' | 'review' | 'deny', required
    - `reason_codes` string[], required
    - `matched_rule_ids` string[], required
    - `risk_summary` object, required
      - `maximum_severity` 'none' | 'low' | 'medium' | 'high' | 'critical', required
      - `signal_codes` string[], required
    - `trace_id` string, uuid, required
    - `idempotent_replay` boolean, required

## Other responses

- `400`: Strict action schema invalid
- `401`: Missing or invalid API key
- `403`: Missing actions:authorize scope or agent binding mismatch
- `404`: Tenant-bound source, Evidence or executor not found
- `409`: Idempotency conflict or no active policy
- `413`: Request exceeds 65536 bytes
- `429`: Tenant-agent authorization rate limit exceeded
- `503`: Gate disabled or authorization authority unavailable

---

[API](https://skmtc.dev/thrd/apis/thrd-agent-email-api.md) · [All operations](https://skmtc.dev/thrd/apis/thrd-agent-email-api/llms.txt) · [OpenAPI document](https://skmtc.dev/thrd/apis/thrd-agent-email-api/revisions/d8a88129cd34?raw)