Authorization and outcome API

Authorization evaluates one request under an active policy. The request binds the authenticated subject, human actor, action, resource, context, audience, environment, nonce, and idempotency identity. Your backend supplies and freezes these values after checking application permissions.

Interpret the response

A successful response returns allow, challenge, hold, or deny. Inspect mode as well as decision. An enforceable allow requires proof verification and online consumption before business execution. Use test and shadow responses for policy inspection and evaluation.

The immediate authorization response carries a compact proof string when applicable. The trace retrieval response carries a nested proof object with compact. A challenge or approved review can create a child authorization; verify its association with the original server-held pending request before using it.

Idempotency, review, and outcomes

Reuse one idempotency key only for retries of the same request material. A changed destination, subject, audience, or context is a new request. Preserve the nonce and request binding for a retry; resolve a binding conflict before submitting a new operation. A stale stored authorization can require fresh authorization after lifecycle or policy changes.

A review records an attributed approve or reject resolution. Your backend executes the action after the resulting authorization passes verification. Fetch and verify any resulting child authorization through the same binding and consumption checks.

Report the actual business outcome after execution or refusal. One outcome is stored per authorization; identical repeats are idempotent and contradictory updates are refused. Your application supplies outcome labels and maintains the evidence supporting them. Use your own retryable outbox for outcome reporting so a failed report never repeats the business mutation.

The Integration guide explains the complete pending-request and crash boundary. The operation contracts below describe authorization, trace retrieval, review, and outcome reporting.

GET /api/v1/authorizations/{authorization_id}

Retrieve the stored authorization identified by the request path. To resolve a challenge or review child, fetch the resulting child authorization ID explicitly.

Credential: Server credential.

Inputs: Backend-selected authorization id. Treat an id delivered by the browser as an untrusted candidate until bound to the original pending request.

Effect and retry behavior: Read-only. A challenge or review child carries parent; require it to equal the original authorization. The proof field is a nested object, unlike the immediate response string.

Parameters

Name / location	Required	Meaning, type and constraints
`authorization_id` (path)	Yes	Authorization identifier returned by a prior request or trusted challenge receipt. string

Responses

HTTP status	Meaning	Body
`200`	Full trace including original binding, parent relation and nested challenge/proof/review/outcome state.	application/json: `AuthorizationTrace`
`422`	The canonical handler returns a Problem for invalid input; correct the request before retrying.	application/problem+json: `Problem`

Response handling: 404 for an unavailable trace. Wrong parent, subject, audience, mode, action or independent action hash requires refusal even when lookup succeeded.

Example

HTTP

GET /api/v1/authorizations/az_child_example

Response excerpt (selected fields) - HTTP 200:

{
  "id": "az_child_example",
  "parent": "az_example",
  "subject": "sub_example",
  "action": "payout.destination.change",
  "decision": "hold",
  "mode": "shadow",
  "proof": null
}

POST /api/v1/authorizations/{authorization_id}/outcome

Record the outcome actually observed by the customer application after a decision.

Credential: Server credential.

Inputs: Choose the declared outcome label. Optional note is retained as a digest; use a minimal, non-confidential reference.

Effect and retry behavior: Stores one outcome per authorization. Identical repeats are idempotent; contradictory outcome updates conflict. Use an application outbox so reporting never repeats execution.

Parameters

Name / location	Required	Meaning, type and constraints
`authorization_id` (path)	Yes	Authorization identifier returned by a prior request or trusted challenge receipt. string

Request body

application/json; required. OutcomeReport.

Responses

HTTP status	Meaning	Body
`200`	Recorded authorization id, outcome label and report timestamp.	application/json: `OutcomeReceipt`
`422`	The canonical handler returns a Problem for invalid input; correct the request before retrying.	application/problem+json: `Problem`

Response handling: 409 when a different outcome was already recorded; 404 for an unavailable authorization. Report executed after proof consumption and confirmed application execution.

Example

HTTP

POST /api/v1/authorizations/az_example/outcome

JSON request

{
  "outcome": "not_executed"
}

Response - HTTP 200:

{
  "authorization": "az_example",
  "outcome": "not_executed",
  "reported_at": "2026-10-01T12:00:00Z"
}

POST /api/v1/authorizations/{authorization_id}/review

Record an attributed administrator approve/reject resolution for manual review.

Credential: Admin server credential.

Inputs: Use the held authorization id. resolution is approve or reject; note is optional and retained as a digest.

Effect and retry behavior: Reject records a rejection outcome. Approve reevaluates a child request. Fetch the child decision and verify its proof before executing an eligible business operation.

Parameters

Name / location	Required	Meaning, type and constraints
`authorization_id` (path)	Yes	Authorization identifier returned by a prior request or trusted challenge receipt. string

Request body

application/json; required. ManualReviewRequest.

Responses

HTTP status	Meaning	Body
`200`	Reject returns an outcome receipt; approve returns a fresh child decision that may still refuse execution.	application/json: `ReviewApprovedReceipt` or `ReviewRejectedReceipt`
`422`	The canonical handler returns a Problem for invalid input; correct the request before retrying.	application/problem+json: `Problem`

Response handling: Ineligible decision state, duplicate/conflicting resolution and lifecycle changes are refused. Require parent and original binding checks on any approved child.

Example

HTTP

POST /api/v1/authorizations/az_example/review

JSON request

{
  "resolution": "reject"
}

Response - HTTP 200:

{
  "authorization": "az_example",
  "resolution": "reject",
  "outcome": {
    "authorization": "az_example",
    "outcome": "manually_rejected",
    "reported_at": "2026-10-01T12:00:00Z"
  }
}

POST /api/v1/authorize

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

Credential: Server credential.

Inputs: Derive subject, actor, resource and context on the backend. Persist requested_at (Unix seconds), a fresh nonce, idempotency_key and independently computed action hash before calling.

Effect and retry behavior: Stores a decision trace and may issue a challenge or enforce-mode proof and record qualifying usage. Identical retries reuse the request identity; changed material must be a new request.

Request body

application/json; required. AuthorizeRequest.

Responses

HTTP status	Meaning	Body
`200`	Decision, mode, independent-binding digest, policy version, reasons and Assurance Profile; challenge or proof appears only when applicable.	application/json: `AuthorizeResponse`
`422`	The canonical handler returns a Problem for invalid input; correct the request before retrying.	application/problem+json: `Problem`

Response handling: Unregistered/inactive actions, invalid context, disallowed caller/audience, stale request, nonce reuse and conflicting idempotency are refused. An HTTP 200 deny/hold/challenge still requires non-execution.

Example

HTTP

POST /api/v1/authorize

JSON request

{
  "subject": "sub_example",
  "actor": {
    "id": "sub_example",
    "type": "human"
  },
  "action": "payout.destination.change",
  "resource": {
    "type": "merchant",
    "id": "merchant_42"
  },
  "context": {
    "destination_fingerprint": "bank-destination-fingerprint-7"
  },
  "audience": "merchant-api",
  "requested_at": 1790856000,
  "nonce": "2de95a66-712e-4a60-9ccf-3c9b53e442fa",
  "idempotency_key": "payout-change-42-request-7",
  "session": "ses_example"
}

Response - HTTP 200:

{
  "id": "az_example",
  "decision": "challenge",
  "mode": "shadow",
  "action": "payout.destination.change",
  "environment": "env_example",
  "policy_version": 1,
  "challenge": {
    "id": "ch_example",
    "methods": [
      "passkey"
    ],
    "expires_at": "2026-10-01T12:05:00Z"
  },
  "proof": null,
  "action_hash": "15ffd65a68fe273d7982c94152aa6e974e4f4b182e1733cc96fed169cfec22ea",
  "reason_codes": [
    "decision.insufficient_evidence"
  ],
  "human_readable": {
    "status": "challenge",
    "detail": "Additional action-bound confirmation is required."
  },
  "assurance": {
    "id": "asr_example",
    "subject": "sub_example",
    "session": "ses_example",
    "assessed_at": "2026-10-01T12:00:00Z",
    "claims": [],
    "coverage": "none",
    "evidence_windows": 0,
    "active_seconds": 0.0,
    "modalities_present": [],
    "freshness_ms": null,
    "limitations": [
      "insufficient evidence"
    ],
    "model_version": "example-model-version",
    "rule_version": "example-rule-version",
    "feature_schema_version": "example-feature-version",
    "insufficient_evidence": true
  },
  "proof_id": null,
  "trace_id": "az_example",
  "decided_at": "2026-10-01T12:00:00Z",
  "latency_ms": 12
}