Protected actions and policies

A protected action names one consequential operation in your application. Register a stable dotted key, a human-readable name and consequence, a risk class, a resource type, and the context fields that distinguish one request from another. Each authorization uses a specific immutable policy version.

Choose the action boundary

For a destination change, bind the merchant resource and the exact destination fingerprint. For a permission grant, bind the target account, role, and relevant scope. For a sensitive export, bind the dataset, selection, recipient, and export purpose when those values determine what is approved. Validate all of these values on your backend before requesting a decision.

Give each action enough context to identify its exact destination, dataset, or other consequential values. Use integers for amounts in minor units and strings for identifiers; floating-point values are not accepted in canonical action context.

Action modes

New actions start in shadow mode. Configure the mode independently of the policy version through the action mode API or Console. Use sandbox enforce mode for proof verification and consumption around a mock operation, and live shadow mode for evaluation. For error.enforcement_not_approved, retain the current mode and contact support with the environment and trace ID.

Immutable policy versions

A policy version snapshots context schema, audiences, allowed callers, proof lifetime, assurance requirements, missing-evidence behavior, challenge methods and compensation, and hold and deny conditions. Each version has an integrity digest. A digest mismatch causes authorization to fail closed.

Create a new version for a security-relevant change, review it, then activate it. Activation retires the previous active version in the same transaction. To roll back, activate a reviewed prior version rather than editing an immutable record. Keep the action ID and policy version with deployment records, incident traces, and evaluation results.

The following illustrative policy request body requires explicit approval. Submit it to the policy-version creation operation for your action, then activate the returned version with an admin credential. The action reference lists the exact endpoints and fields:

{
  "requirements": {
    "claims": { "operator_continuity": "uncertain" },
    "coverage_min": "partial",
    "freshness_max_ms": 60000,
    "insufficient_evidence": "challenge",
    "challenge_methods": ["passkey"],
    "explicit_approval_required": true,
    "challenge_compensates": ["operator_continuity", "coverage", "freshness"],
    "hold_on": ["operator_change.detected", "automation.detected"],
    "deny_on": []
  },
  "allowed_audiences": ["payments-app"],
  "proof_ttl_seconds": 300,
  "context_schema": {
    "type": "object",
    "required": ["destination_fingerprint"],
    "properties": {
      "destination_fingerprint": {
        "type": "string", "minLength": 64, "maxLength": 64
      }
    },
    "additionalProperties": false
  }
}

Choose freshness, coverage, compensation, and proof lifetime for the workflow you are evaluating. The example values illustrate the request contract; evaluate their effect on challenges and holds before adopting them. After activation, confirm the action reports the intended active policy version. If activation conflicts with a concurrent update, re-read the action before retrying.

Context schema support

The supported schema subset includes type, properties, required, additionalProperties, enum, minLength, maxLength, minimum, maximum, items, title, and description. Types include object, string, integer, boolean, array, and null. Unsupported keywords and malformed schema values are rejected at registration. Required properties must be declared, and excessive nesting is rejected.

Use additionalProperties: false where the approved request shape is fixed. Schema validation checks shape and type. Your backend separately verifies merchant ownership and permission to change the destination.

Decision precedence

GrayPass validates the registered action, active policy integrity, resource type, schema, caller, audience, request freshness, idempotency, and nonce before applying policy. Deny and hold conditions take precedence over compensable missing evidence. Operator-change and automation hold conditions remain part of the policy evaluation after challenge completion.

Insufficient evidence maps to challenge, hold, or denial according to policy. When the result differs from your expectation, inspect accepted evidence, policy intent, and the resulting reasons using Troubleshooting.