---
title: "Evaluate a bound business request"
method: POST
path: "/api/v1/authorize"
tags: ["canonical"]
---

# Evaluate a bound business request

`POST /api/v1/authorize`

## Request

- Base URL: `https://app.graypass.org` (the document declares no server; this is the origin it was published from)
- URL: `https://app.graypass.org/api/v1/authorize`
- Auth: HTTP bearer

Evaluate one immutable request against the action’s active policy and return allow, challenge, hold or deny.

## Request body

- AuthorizeRequest: Immutable business-request material supplied by the relying-party backend after its own authentication and permission checks.
  - `action` string, required: Registered action key, such as payout.destination.change.
  - `actor` Actor: Actor bound to the protected business request.
    - `id` string, required: Application actor identifier. Use the subject identifier for the supported human proof-verification path.
    - `type` 'human': Actor category; only human is supported in this API version.
  - `audience` string, required: Expected relying-party audience. It must be permitted by the action and independently known to the verifier.
  - `context` object: Business values bound to the decision and validated against the active context schema. Use safe integers rather than floating-point values.
  - `idempotency_key` string, required: Stable application request identifier reused only for identical retries; changed material with the same key conflicts.
  - `mandate_ref` string, nullable: Supported value: null. Omit the field or send null.
  - `nonce` string, required: Fresh unpredictable nonce for this request. Retain it with the pending operation and reuse it only for retries of that same request.
  - `requested_at` integer, required: Unix timestamp in seconds; the request must be no older than 300 seconds and no more than 60 seconds in the future. This timestamp is excluded from the action hash and idempotency comparison; a retry can refresh it without changing the original nonce or business material.
  - `resource` Resource, required: Exact business resource bound to an authorization.
    - `id` string, required: Application resource identifier, derived from the authenticated pending business request.
    - `type` string, required: Application resource category, such as merchant.
  - `session` string, nullable: Optional observation session for this subject. When omitted, the service selects the subject’s latest applicable session.
  - `subject` string, required: Pseudonymous subject identifier in the authenticated tenant and environment.

## Response `200`

Decision, mode, independent-binding digest, policy version, reasons and Assurance Profile; challenge or proof appears only when applicable.

- AuthorizeResponse: Immediate policy result. Only an enforce-mode allow can include a compact Proof of Agency.
  - `action` string, required: Registered action key, such as payout.destination.change.
  - `action_hash` string, required: SHA-256 digest binding the canonical authorization material. Compare it with the hash computed from the original server-held request.
  - `assurance` AssuranceProfile, required: Server assessment of available evidence for one subject and session. It contains no calibrated confidence score.
    - `active_seconds` number: Duration of accepted active evidence in seconds.
    - `assessed_at` string, required: Assessment time as an ISO 8601 timestamp.
    - `claims` AssuranceClaim[], required: Individual assurance claims with their own status and limitations.
      - `claim` string, required: Claim name, such as operator_continuity or human_presence. Capability availability is separately reported by metadata.
      - `coverage` 'none' | 'sparse' | 'partial' | 'sufficient', required: Evidence-coverage category: none, sparse, partial or sufficient. Describes the amount and variety of accepted evidence.
      - `evidence_refs` string[]: Opaque references to the evidence supporting this claim.
      - `freshness_ms` integer, nullable: Age of the relevant evidence in milliseconds; null when freshness cannot be established.
      - `limitations` string[]: Applicable limitations that must accompany interpretation of the result.
      - `reason_codes` string[]: Stable reason identifiers explaining acceptance, limitations or a decision; resolve them in the reason-code catalog.
      - `status` 'confirmed' | 'likely' | 'uncertain' | 'not_confirmed' | 'detected' | 'not_detected' | 'not_present' | 'insufficient_evidence' | 'unsupported', required: Permitted statuses for a named assurance claim. Read the status with the claim definition, coverage, freshness, and assessment context.
    - `coverage` 'none' | 'sparse' | 'partial' | 'sufficient', required: Evidence-coverage category: none, sparse, partial or sufficient. Describes the amount and variety of accepted evidence.
    - `evidence_windows` integer: Number of accepted, non-overlapping evidence windows accounted for in this session or profile.
    - `feature_schema_version` string, required: Version identifier for the feature representation used by the session or assessment.
    - `freshness_ms` integer, nullable: Age of the relevant evidence in milliseconds; null when freshness cannot be established.
    - `id` string, required: Identifier of this record. Treat it as opaque and retain it for subsequent operations.
    - `insufficient_evidence` boolean, required: True when evidence is insufficient for the assessment’s supported claims.
    - `limitations` string[]: Applicable limitations that must accompany interpretation of the result.
    - `modalities_present` string[]: Names of observed evidence modalities included in coverage accounting.
    - `model_version` string, required: Version identifier for the model used in this assessment. Retain it when comparing assessment results.
    - `rule_version` string, required: Version identifier for the assurance rules used in this assessment.
    - `session` string, nullable: Observation or enrollment session identifier, as required by the operation.
    - `subject` string, required: Pseudonymous subject identifier in the authenticated tenant and environment.
  - `challenge` ChallengeDescriptor: Challenge offered by an authorization decision, including methods and expiry.
    - `expires_at` string, required: Expiry time as an ISO 8601 timestamp. Use the capability before this time; obtain a fresh one afterward.
    - `id` string, required: Identifier of this record. Treat it as opaque and retain it for subsequent operations.
    - `methods` string[], required: Permitted challenge methods. sandbox_confirm is a simulated ceremony restricted to the sandbox.
  - `decided_at` string, required: Decision time as an ISO 8601 timestamp.
  - `decision` 'allow' | 'challenge' | 'hold' | 'deny', required: Policy result: allow, challenge, hold or deny. Inspect mode and proof requirements before performing any business mutation.
  - `environment` string, required: Environment identifier that scopes this record; sandbox and live resources are separate.
  - `human_readable` HumanReadable, required: Customer-display wording explaining a decision; stable reason codes carry the programmatic meaning.
    - `detail` string, required: Human-readable explanation. Use stable codes and typed decision fields for application branching.
    - `status` string, required: Short display label for the decision; use reason codes for stable programmatic behavior.
  - `id` string, required: Identifier of this record. Treat it as opaque and retain it for subsequent operations.
  - `latency_ms` integer, required: Server-recorded decision latency in milliseconds.
  - `mode` 'test' | 'shadow' | 'enforce', required: Action evaluation mode. Test and shadow return decisions without enforceable proofs. An eligible enforce-mode allow can carry a proof.
  - `policy_version` integer, required: Immutable policy version number evaluated for this decision.
  - `proof` string, nullable: Compact signed JWS, or null. Require enforce-mode allow, trusted binding checks and successful online consumption before execution.
  - `proof_id` string, nullable: Proof identifier (jti), or null when no proof was issued.
  - `reason_codes` string[], required: Stable reason identifiers explaining acceptance, limitations or a decision; resolve them in the reason-code catalog.
  - `trace_id` string, required: Identifier to retain for authorization trace lookup and operational diagnosis.

## Other responses

- `422`: The canonical handler returns a Problem for invalid input; correct the request before retrying.

---

[API](https://skmtc.dev/graypass/apis/graypass-api.md) - [All operations](https://skmtc.dev/graypass/apis/graypass-api/llms.txt) - [OpenAPI document](https://skmtc.dev/graypass/apis/graypass-api/revisions/5f9ab64fdfdb?raw)