{
  "components": {
    "schemas": {
      "ActionCreate": {
        "additionalProperties": false,
        "description": "Register a protected action and its initial policy settings.",
        "properties": {
          "allowed_audiences": {
            "description": "Relying-party audience identifiers allowed to receive proofs for this action.",
            "items": {
              "type": "string"
            },
            "minItems": 1,
            "type": "array"
          },
          "allowed_callers": {
            "description": "Credential identifiers allowed to authorize this action. An empty list permits any eligible server credential in the same environment.",
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "consequence": {
            "description": "Plain-language consequence if the wrong person performs the protected action.",
            "maxLength": 500,
            "minLength": 1,
            "type": "string"
          },
          "context_schema": {
            "additionalProperties": true,
            "description": "JSON Schema object applied to authorization context. Include every business value that must be bound to approval.",
            "type": "object"
          },
          "key": {
            "description": "Stable dotted action key used by authorization, such as payout.destination.change.",
            "maxLength": 128,
            "pattern": "^[a-z][a-z0-9_]*(\\.[a-z][a-z0-9_]*)*$",
            "type": "string"
          },
          "name": {
            "description": "Customer-visible display name for the action or evaluation.",
            "maxLength": 120,
            "minLength": 1,
            "type": "string"
          },
          "proof_ttl_seconds": {
            "default": 300,
            "description": "Proof lifetime in seconds, measured from issuance; the accepted range is 30-900 seconds.",
            "maximum": 900.0,
            "minimum": 30.0,
            "type": "integer"
          },
          "resource_type": {
            "default": "resource",
            "description": "Customer-defined category of the protected resource, such as merchant.",
            "maxLength": 64,
            "type": "string"
          },
          "risk_class": {
            "default": "high",
            "description": "Customer-selected consequence category for the action: low, elevated, high or critical.",
            "enum": [
              "low",
              "elevated",
              "high",
              "critical"
            ],
            "type": "string"
          }
        },
        "required": [
          "key",
          "name",
          "consequence",
          "allowed_audiences"
        ],
        "title": "ActionCreate",
        "type": "object"
      },
      "ActionUpdate": {
        "additionalProperties": false,
        "description": "Change action display metadata or evaluation mode; policy security settings are versioned separately.",
        "properties": {
          "consequence": {
            "anyOf": [
              {
                "maxLength": 500,
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Plain-language consequence if the wrong person performs the protected action."
          },
          "mode": {
            "anyOf": [
              {
                "enum": [
                  "test",
                  "shadow",
                  "enforce"
                ],
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Action evaluation mode. Test and shadow return decisions without enforceable proofs. An eligible enforce-mode allow can carry a proof. Omit to keep the current mode."
          },
          "name": {
            "anyOf": [
              {
                "maxLength": 120,
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Customer-visible display name for the action or evaluation."
          }
        },
        "title": "ActionUpdate",
        "type": "object"
      },
      "Actor": {
        "additionalProperties": false,
        "description": "Actor bound to the protected business request.",
        "properties": {
          "id": {
            "description": "Application actor identifier. Use the subject identifier for the supported human proof-verification path.",
            "maxLength": 256,
            "minLength": 1,
            "type": "string"
          },
          "type": {
            "const": "human",
            "default": "human",
            "description": "Actor category; only human is supported in this API version.",
            "type": "string"
          }
        },
        "required": [
          "id"
        ],
        "title": "Actor",
        "type": "object"
      },
      "AssuranceClaim": {
        "additionalProperties": false,
        "description": "A named evidence claim with categorical status, coverage, freshness, and assessment context.",
        "properties": {
          "claim": {
            "description": "Claim name, such as operator_continuity or human_presence. Capability availability is separately reported by metadata.",
            "type": "string"
          },
          "coverage": {
            "description": "Evidence-coverage category: none, sparse, partial or sufficient. Describes the amount and variety of accepted evidence.",
            "enum": [
              "none",
              "sparse",
              "partial",
              "sufficient"
            ],
            "type": "string"
          },
          "evidence_refs": {
            "description": "Opaque references to the evidence supporting this claim.",
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "freshness_ms": {
            "anyOf": [
              {
                "minimum": 0.0,
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "description": "Age of the relevant evidence in milliseconds; null when freshness cannot be established."
          },
          "limitations": {
            "description": "Applicable limitations that must accompany interpretation of the result.",
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "reason_codes": {
            "description": "Stable reason identifiers explaining acceptance, limitations or a decision; resolve them in the reason-code catalog.",
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "status": {
            "$ref": "#/components/schemas/ClaimStatus",
            "description": "Status of this named claim. Use unsupported and insufficient_evidence to select the configured evidence-collection or approval path."
          }
        },
        "required": [
          "claim",
          "status",
          "coverage"
        ],
        "title": "AssuranceClaim",
        "type": "object"
      },
      "AssuranceProfile": {
        "additionalProperties": false,
        "description": "Server assessment of available evidence for one subject and session. It contains no calibrated confidence score.",
        "properties": {
          "active_seconds": {
            "default": 0.0,
            "description": "Duration of accepted active evidence in seconds.",
            "type": "number"
          },
          "assessed_at": {
            "description": "Assessment time as an ISO 8601 timestamp.",
            "type": "string"
          },
          "claims": {
            "description": "Individual assurance claims with their own status and limitations.",
            "items": {
              "$ref": "#/components/schemas/AssuranceClaim"
            },
            "type": "array"
          },
          "coverage": {
            "description": "Evidence-coverage category: none, sparse, partial or sufficient. Describes the amount and variety of accepted evidence.",
            "enum": [
              "none",
              "sparse",
              "partial",
              "sufficient"
            ],
            "type": "string"
          },
          "evidence_windows": {
            "default": 0,
            "description": "Number of accepted, non-overlapping evidence windows accounted for in this session or profile.",
            "type": "integer"
          },
          "feature_schema_version": {
            "description": "Version identifier for the feature representation used by the session or assessment.",
            "type": "string"
          },
          "freshness_ms": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "description": "Age of the relevant evidence in milliseconds; null when freshness cannot be established."
          },
          "id": {
            "description": "Identifier of this record. Treat it as opaque and retain it for subsequent operations.",
            "type": "string"
          },
          "insufficient_evidence": {
            "description": "True when evidence is insufficient for the assessment\u2019s supported claims.",
            "type": "boolean"
          },
          "limitations": {
            "description": "Applicable limitations that must accompany interpretation of the result.",
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "modalities_present": {
            "description": "Names of observed evidence modalities included in coverage accounting.",
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "model_version": {
            "description": "Version identifier for the model used in this assessment. Retain it when comparing assessment results.",
            "type": "string"
          },
          "rule_version": {
            "description": "Version identifier for the assurance rules used in this assessment.",
            "type": "string"
          },
          "session": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Observation or enrollment session identifier, as required by the operation."
          },
          "subject": {
            "description": "Pseudonymous subject identifier in the authenticated tenant and environment.",
            "type": "string"
          }
        },
        "required": [
          "id",
          "subject",
          "assessed_at",
          "claims",
          "coverage",
          "model_version",
          "rule_version",
          "feature_schema_version",
          "insufficient_evidence"
        ],
        "title": "AssuranceProfile",
        "type": "object"
      },
      "AuthorizationTrace": {
        "description": "Server-readable record of the original request binding, decision and subsequent challenge, proof, review and outcome state.",
        "properties": {
          "action": {
            "description": "Registered action key, such as payout.destination.change.",
            "type": "string"
          },
          "action_hash": {
            "description": "SHA-256 digest binding the canonical authorization material. Compare it with the hash computed from the original server-held request.",
            "type": "string"
          },
          "actor": {
            "description": "Bound human actor identifier.",
            "type": "string"
          },
          "actor_type": {
            "const": "human",
            "description": "Bound actor category; only human is supported.",
            "type": "string"
          },
          "assurance": {
            "$ref": "#/components/schemas/AssuranceProfile",
            "description": "Assurance Profile used for this authorization decision."
          },
          "audience": {
            "description": "Expected relying-party audience. It must be permitted by the action and independently known to the verifier.",
            "type": "string"
          },
          "challenge": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/ChallengeTrace"
              },
              {
                "type": "null"
              }
            ],
            "description": "Challenge associated with the request. Null means no challenge is included in this response."
          },
          "context_digest": {
            "description": "Digest of the context binding. Render your independently retained business details for user confirmation.",
            "type": "string"
          },
          "decided_at": {
            "description": "Decision time as an ISO 8601 timestamp.",
            "type": "string"
          },
          "decision": {
            "description": "Policy result: allow, challenge, hold or deny. Inspect mode and proof requirements before performing any business mutation.",
            "enum": [
              "allow",
              "challenge",
              "hold",
              "deny"
            ],
            "type": "string"
          },
          "id": {
            "description": "Identifier of this record. Treat it as opaque and retain it for subsequent operations.",
            "type": "string"
          },
          "latency_ms": {
            "description": "Server-recorded decision latency in milliseconds.",
            "type": "integer"
          },
          "mode": {
            "description": "Action evaluation mode. Test and shadow return decisions without enforceable proofs. An eligible enforce-mode allow can carry a proof.",
            "enum": [
              "test",
              "shadow",
              "enforce"
            ],
            "type": "string"
          },
          "outcome": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Business outcome reported by the customer application, with supporting evidence maintained by the customer."
          },
          "outcome_reported_at": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Recorded business-outcome time as an ISO 8601 timestamp, or null."
          },
          "parent": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Parent authorization identifier for a challenge or review child; null for an original request."
          },
          "policy_version": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "description": "Immutable policy version number evaluated for this decision."
          },
          "proof": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/ProofTrace"
              },
              {
                "type": "null"
              }
            ],
            "description": "Nested proof state. Its compact field carries the signed proof; AuthorizeResponse.proof carries the compact string directly."
          },
          "proof_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Proof identifier (jti), or null when no proof was issued."
          },
          "reason_codes": {
            "description": "Stable reason identifiers explaining acceptance, limitations or a decision; resolve them in the reason-code catalog.",
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "requested_at": {
            "description": "Recorded request time as an ISO 8601 timestamp in the trace, distinct from the caller\u2019s Unix-seconds input.",
            "type": "string"
          },
          "resource_digest": {
            "description": "One-way digest of the resource binding.",
            "type": "string"
          },
          "resource_type": {
            "description": "Customer-defined category of the protected resource, such as merchant.",
            "type": "string"
          },
          "review_authorization_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Child authorization produced by an approved review, or null."
          },
          "review_status": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Recorded manual-review state, or null when no review occurred."
          },
          "reviewed_at": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Manual-review time as an ISO 8601 timestamp, or null."
          },
          "reviewed_by": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Identifier of the credential attributed to the manual review, or null."
          },
          "subject": {
            "description": "Pseudonymous subject identifier in the authenticated tenant and environment.",
            "type": "string"
          }
        },
        "required": [
          "id",
          "action",
          "subject",
          "actor",
          "actor_type",
          "resource_type",
          "resource_digest",
          "context_digest",
          "action_hash",
          "audience",
          "mode",
          "decision",
          "reason_codes",
          "assurance",
          "requested_at",
          "decided_at",
          "latency_ms"
        ],
        "title": "AuthorizationTrace",
        "type": "object"
      },
      "AuthorizeRequest": {
        "additionalProperties": false,
        "description": "Immutable business-request material supplied by the relying-party backend after its own authentication and permission checks.",
        "properties": {
          "action": {
            "description": "Registered action key, such as payout.destination.change.",
            "maxLength": 128,
            "type": "string"
          },
          "actor": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/Actor"
              },
              {
                "type": "null"
              }
            ],
            "description": "Optional explicit human actor. When omitted, the subject is the actor. Use that same subject identifier for the supported human proof-verification path."
          },
          "audience": {
            "description": "Expected relying-party audience. It must be permitted by the action and independently known to the verifier.",
            "maxLength": 128,
            "minLength": 1,
            "type": "string"
          },
          "context": {
            "additionalProperties": true,
            "description": "Business values bound to the decision and validated against the active context schema. Use safe integers rather than floating-point values.",
            "type": "object"
          },
          "idempotency_key": {
            "description": "Stable application request identifier reused only for identical retries; changed material with the same key conflicts.",
            "maxLength": 128,
            "minLength": 8,
            "type": "string"
          },
          "mandate_ref": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Supported value: null. Omit the field or send null."
          },
          "nonce": {
            "description": "Fresh unpredictable nonce for this request. Retain it with the pending operation and reuse it only for retries of that same request.",
            "maxLength": 128,
            "minLength": 16,
            "type": "string"
          },
          "requested_at": {
            "description": "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.",
            "minimum": 0.0,
            "type": "integer"
          },
          "resource": {
            "$ref": "#/components/schemas/Resource",
            "description": "Resource type and identifier for the exact object being changed."
          },
          "session": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Optional observation session for this subject. When omitted, the service selects the subject\u2019s latest applicable session."
          },
          "subject": {
            "description": "Pseudonymous subject identifier in the authenticated tenant and environment.",
            "type": "string"
          }
        },
        "required": [
          "subject",
          "action",
          "resource",
          "audience",
          "requested_at",
          "nonce",
          "idempotency_key"
        ],
        "title": "AuthorizeRequest",
        "type": "object"
      },
      "AuthorizeResponse": {
        "description": "Immediate policy result. Only an enforce-mode allow can include a compact Proof of Agency.",
        "properties": {
          "action": {
            "description": "Registered action key, such as payout.destination.change.",
            "type": "string"
          },
          "action_hash": {
            "description": "SHA-256 digest binding the canonical authorization material. Compare it with the hash computed from the original server-held request.",
            "type": "string"
          },
          "assurance": {
            "$ref": "#/components/schemas/AssuranceProfile",
            "description": "Assurance Profile used for the decision."
          },
          "challenge": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/ChallengeDescriptor"
              },
              {
                "type": "null"
              }
            ],
            "description": "Challenge associated with the request. Null means no challenge is included in this response."
          },
          "decided_at": {
            "description": "Decision time as an ISO 8601 timestamp.",
            "type": "string"
          },
          "decision": {
            "description": "Policy result: allow, challenge, hold or deny. Inspect mode and proof requirements before performing any business mutation.",
            "enum": [
              "allow",
              "challenge",
              "hold",
              "deny"
            ],
            "type": "string"
          },
          "environment": {
            "description": "Environment identifier that scopes this record; sandbox and live resources are separate.",
            "type": "string"
          },
          "human_readable": {
            "$ref": "#/components/schemas/HumanReadable",
            "description": "Display status and detail explaining the result. Branch on the stable decision and reason-code fields."
          },
          "id": {
            "description": "Identifier of this record. Treat it as opaque and retain it for subsequent operations.",
            "type": "string"
          },
          "latency_ms": {
            "description": "Server-recorded decision latency in milliseconds.",
            "type": "integer"
          },
          "mode": {
            "description": "Action evaluation mode. Test and shadow return decisions without enforceable proofs. An eligible enforce-mode allow can carry a proof.",
            "enum": [
              "test",
              "shadow",
              "enforce"
            ],
            "type": "string"
          },
          "policy_version": {
            "description": "Immutable policy version number evaluated for this decision.",
            "type": "integer"
          },
          "proof": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Compact signed JWS, or null. Require enforce-mode allow, trusted binding checks and successful online consumption before execution."
          },
          "proof_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Proof identifier (jti), or null when no proof was issued."
          },
          "reason_codes": {
            "description": "Stable reason identifiers explaining acceptance, limitations or a decision; resolve them in the reason-code catalog.",
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "trace_id": {
            "description": "Identifier to retain for authorization trace lookup and operational diagnosis.",
            "type": "string"
          }
        },
        "required": [
          "id",
          "decision",
          "mode",
          "action",
          "action_hash",
          "environment",
          "policy_version",
          "reason_codes",
          "human_readable",
          "assurance",
          "trace_id",
          "decided_at",
          "latency_ms"
        ],
        "title": "AuthorizeResponse",
        "type": "object"
      },
      "ChallengeCancelled": {
        "description": "Acknowledgment that the selected challenge was cancelled.",
        "properties": {
          "id": {
            "description": "Identifier of this record. Treat it as opaque and retain it for subsequent operations.",
            "type": "string"
          },
          "status": {
            "const": "cancelled",
            "description": "Lifecycle state of this record; use the operation-specific values listed in the schema.",
            "type": "string"
          }
        },
        "required": [
          "id",
          "status"
        ],
        "title": "ChallengeCancelled",
        "type": "object"
      },
      "ChallengeCompleteRequest": {
        "additionalProperties": false,
        "description": "Complete an action-bound challenge using one of its permitted methods.",
        "properties": {
          "assertion": {
            "anyOf": [
              {
                "additionalProperties": true,
                "type": "object"
              },
              {
                "type": "null"
              }
            ],
            "description": "WebAuthn authentication assertion produced for this challenge\u2019s options when method is passkey. Omit for sandbox_confirm."
          },
          "method": {
            "description": "Chosen challenge method; use only a method offered by this challenge.",
            "enum": [
              "passkey",
              "sandbox_confirm"
            ],
            "type": "string"
          }
        },
        "required": [
          "method"
        ],
        "title": "ChallengeCompleteRequest",
        "type": "object"
      },
      "ChallengeCompletionReceipt": {
        "description": "Browser-safe completion receipt. The backend must retrieve and validate the referenced child authorization.",
        "properties": {
          "authorization": {
            "description": "Authorization identifier associated with this receipt. Resolve it on the backend and verify the bound proof before execution.",
            "type": "string"
          },
          "challenge": {
            "description": "Completed challenge identifier.",
            "type": "string"
          },
          "method": {
            "description": "Chosen challenge method; use only a method offered by this challenge.",
            "enum": [
              "passkey",
              "sandbox_confirm"
            ],
            "type": "string"
          },
          "status": {
            "const": "completed",
            "description": "Lifecycle state of this record; use the operation-specific values listed in the schema.",
            "type": "string"
          }
        },
        "required": [
          "challenge",
          "status",
          "authorization",
          "method"
        ],
        "title": "ChallengeCompletionReceipt",
        "type": "object"
      },
      "ChallengeDescriptor": {
        "description": "Challenge offered by an authorization decision, including methods and expiry.",
        "properties": {
          "expires_at": {
            "description": "Expiry time as an ISO 8601 timestamp. Use the capability before this time; obtain a fresh one afterward.",
            "type": "string"
          },
          "id": {
            "description": "Identifier of this record. Treat it as opaque and retain it for subsequent operations.",
            "type": "string"
          },
          "methods": {
            "description": "Permitted challenge methods. sandbox_confirm is a simulated ceremony restricted to the sandbox.",
            "items": {
              "enum": [
                "passkey",
                "sandbox_confirm"
              ],
              "type": "string"
            },
            "type": "array"
          }
        },
        "required": [
          "id",
          "methods",
          "expires_at"
        ],
        "title": "ChallengeDescriptor",
        "type": "object"
      },
      "ChallengeDisplay": {
        "description": "Display information for explicit action confirmation. Digests complement the relying party\u2019s independently retained business details.",
        "properties": {
          "action": {
            "description": "Customer-visible protected-action name.",
            "type": "string"
          },
          "action_key": {
            "description": "Stable registered key for the action being approved.",
            "type": "string"
          },
          "audience": {
            "description": "Expected relying-party audience. It must be permitted by the action and independently known to the verifier.",
            "type": "string"
          },
          "consequence": {
            "description": "Plain-language consequence if the wrong person performs the protected action.",
            "type": "string"
          },
          "context_digest": {
            "description": "Digest of the context binding. Render your independently retained business details for user confirmation.",
            "type": "string"
          },
          "requesting_application": {
            "description": "Relying-party application identified in the challenge display.",
            "type": "string"
          },
          "resource_digest": {
            "description": "One-way digest of the resource binding.",
            "type": "string"
          },
          "resource_type": {
            "description": "Customer-defined category of the protected resource, such as merchant.",
            "type": "string"
          }
        },
        "required": [
          "action_key",
          "action",
          "consequence",
          "resource_type",
          "resource_digest",
          "context_digest",
          "audience",
          "requesting_application"
        ],
        "title": "ChallengeDisplay",
        "type": "object"
      },
      "ChallengePublicView": {
        "description": "Browser-safe view of a scoped challenge and the action it asks the subject to approve.",
        "properties": {
          "display": {
            "$ref": "#/components/schemas/ChallengeDisplay",
            "description": "Action display metadata and digests bound to the original request."
          },
          "expires_at": {
            "description": "Expiry time as an ISO 8601 timestamp. Use the capability before this time; obtain a fresh one afterward.",
            "type": "string"
          },
          "id": {
            "description": "Identifier of this record. Treat it as opaque and retain it for subsequent operations.",
            "type": "string"
          },
          "methods": {
            "description": "Permitted challenge methods. sandbox_confirm is a simulated ceremony restricted to the sandbox.",
            "items": {
              "enum": [
                "passkey",
                "sandbox_confirm"
              ],
              "type": "string"
            },
            "type": "array"
          },
          "status": {
            "description": "Lifecycle state of this record; use the operation-specific values listed in the schema.",
            "type": "string"
          }
        },
        "required": [
          "id",
          "status",
          "methods",
          "expires_at",
          "display"
        ],
        "title": "ChallengePublicView",
        "type": "object"
      },
      "ChallengeTrace": {
        "description": "Challenge lifecycle state embedded in an authorization trace.",
        "properties": {
          "completed_at": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Completion time as an ISO 8601 timestamp, or null before completion."
          },
          "expires_at": {
            "description": "Expiry time as an ISO 8601 timestamp. Use the capability before this time; obtain a fresh one afterward.",
            "type": "string"
          },
          "id": {
            "description": "Identifier of this record. Treat it as opaque and retain it for subsequent operations.",
            "type": "string"
          },
          "method_used": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Method used to complete the challenge, or null before completion."
          },
          "status": {
            "description": "Lifecycle state of this record; use the operation-specific values listed in the schema.",
            "type": "string"
          },
          "strength": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Recorded challenge assurance label. Distinguishes action-bound passkey confirmation from sandbox simulation."
          }
        },
        "required": [
          "id",
          "status",
          "expires_at"
        ],
        "title": "ChallengeTrace",
        "type": "object"
      },
      "ClaimStatus": {
        "description": "Permitted statuses for a named assurance claim. Read the status with the claim definition, coverage, freshness, and assessment context.",
        "enum": [
          "confirmed",
          "likely",
          "uncertain",
          "not_confirmed",
          "detected",
          "not_detected",
          "not_present",
          "insufficient_evidence",
          "unsupported"
        ],
        "title": "ClaimStatus",
        "type": "string"
      },
      "ClientTokenCreate": {
        "additionalProperties": false,
        "description": "Mint a short-lived, subject-bound browser credential for a registered origin.",
        "properties": {
          "origin": {
            "description": "Exact browser origin including scheme, hostname and non-default port. It must be registered for the tenant.",
            "maxLength": 2048,
            "minLength": 1,
            "type": "string"
          },
          "subject": {
            "description": "Pseudonymous subject identifier in the authenticated tenant and environment.",
            "type": "string"
          },
          "ttl_seconds": {
            "default": 900,
            "description": "Browser-token lifetime in seconds; default 900, permitted range 60-3600.",
            "maximum": 3600.0,
            "minimum": 60.0,
            "type": "integer"
          }
        },
        "required": [
          "subject",
          "origin"
        ],
        "title": "ClientTokenCreate",
        "type": "object"
      },
      "ClientTokenCreated": {
        "description": "Browser credential issuance result. Treat client_token as a secret capability.",
        "properties": {
          "client_token": {
            "description": "Short-lived bearer token for the selected subject and origin. Keep it out of URLs, logs and persistent browser storage.",
            "type": "string"
          },
          "expires_at": {
            "description": "Token expiry as Unix time in seconds, which differs from the ISO timestamps used by most resource records.",
            "type": "number"
          },
          "origin": {
            "description": "Exact browser origin including scheme, hostname and non-default port. It must be registered for the tenant.",
            "type": "string"
          },
          "ttl_seconds": {
            "description": "Browser-token lifetime in seconds; default 900, permitted range 60-3600.",
            "type": "integer"
          }
        },
        "required": [
          "client_token",
          "expires_at",
          "ttl_seconds",
          "origin"
        ],
        "title": "ClientTokenCreated",
        "type": "object"
      },
      "CredentialIdentity": {
        "description": "Non-secret identity and scope of the authenticated server credential, used to establish trusted verification expectations.",
        "properties": {
          "credential": {
            "description": "Public identifier of the calling credential.",
            "type": "string"
          },
          "environment": {
            "description": "Environment identifier that scopes this record; sandbox and live resources are separate.",
            "type": "string"
          },
          "environment_kind": {
            "description": "Environment category: sandbox or live.",
            "enum": [
              "sandbox",
              "live"
            ],
            "type": "string"
          },
          "mode": {
            "description": "Credential key mode, test or live; distinct from an action\u2019s test, shadow or enforce mode.",
            "enum": [
              "test",
              "live"
            ],
            "type": "string"
          },
          "proof_issuer": {
            "description": "Expected proof issuer reported by the trusted configured service; never learn an issuer from an unverified proof.",
            "type": "string"
          },
          "scope": {
            "description": "Credential authority category. Canonical backend routes require server or admin; client scope is insufficient.",
            "enum": [
              "client",
              "server",
              "admin"
            ],
            "type": "string"
          },
          "tenant": {
            "description": "Tenant identifier to bind proof verification to the intended customer.",
            "type": "string"
          }
        },
        "required": [
          "credential",
          "tenant",
          "environment",
          "environment_kind",
          "scope",
          "mode",
          "proof_issuer"
        ],
        "title": "CredentialIdentity",
        "type": "object"
      },
      "Enrollment": {
        "description": "Enrollment attempt and completion state for a subject\u2019s behavioral reference.",
        "properties": {
          "anchor": {
            "description": "Account anchor established by the customer identity process and recorded by GrayPass.",
            "type": "string"
          },
          "completed_at": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Completion time as an ISO 8601 timestamp, or null before completion."
          },
          "created_at": {
            "description": "Creation time as an ISO 8601 timestamp.",
            "type": "string"
          },
          "id": {
            "description": "Identifier of this record. Treat it as opaque and retain it for subsequent operations.",
            "type": "string"
          },
          "limitations": {
            "description": "Applicable limitations that must accompany interpretation of the result.",
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "status": {
            "description": "Lifecycle state of this record; use the operation-specific values listed in the schema.",
            "enum": [
              "pending",
              "completed",
              "failed"
            ],
            "type": "string"
          },
          "subject": {
            "description": "Pseudonymous subject identifier in the authenticated tenant and environment.",
            "type": "string"
          },
          "windows_accepted": {
            "description": "Count of accepted evidence windows recorded for this enrollment.",
            "type": "integer"
          }
        },
        "required": [
          "id",
          "subject",
          "status",
          "anchor",
          "windows_accepted",
          "created_at"
        ],
        "title": "Enrollment",
        "type": "object"
      },
      "EnrollmentComplete": {
        "additionalProperties": false,
        "description": "Ask the server to complete a subject\u2019s enrollment from its ready enrollment session.",
        "properties": {
          "force": {
            "default": false,
            "description": "Whether to replace an existing template after accepted-window, duration and modality readiness checks pass.",
            "type": "boolean"
          },
          "session": {
            "description": "Enrollment-purpose session owned by the subject in the path.",
            "type": "string"
          }
        },
        "required": [
          "session"
        ],
        "title": "EnrollmentComplete",
        "type": "object"
      },
      "Evaluation": {
        "description": "Stored selection, thresholds and observation window for a shadow integration study.",
        "properties": {
          "action_keys": {
            "description": "Registered action keys included in the evaluation; the service deduplicates this selection.",
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "created_at": {
            "description": "Creation time as an ISO 8601 timestamp.",
            "type": "string"
          },
          "ends_at": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Timezone-aware ISO 8601 study end, later than starts_at. Creation defaults to 30 days after the start; closing can shorten this cutoff."
          },
          "id": {
            "description": "Identifier of this record. Treat it as opaque and retain it for subsequent operations.",
            "type": "string"
          },
          "name": {
            "description": "Customer-visible display name for the action or evaluation.",
            "type": "string"
          },
          "starts_at": {
            "description": "Timezone-aware ISO 8601 study start. If omitted during creation, the service uses the current time.",
            "type": "string"
          },
          "status": {
            "description": "Lifecycle state of this record; use the operation-specific values listed in the schema.",
            "enum": [
              "open",
              "closed"
            ],
            "type": "string"
          },
          "success_criteria": {
            "$ref": "#/components/schemas/EvaluationCriteria",
            "description": "Recorded thresholds for shadow-decision count, abstention rate and outcome coverage, evaluated against the selected traces."
          }
        },
        "required": [
          "id",
          "name",
          "action_keys",
          "success_criteria",
          "status",
          "starts_at",
          "created_at"
        ],
        "title": "Evaluation",
        "type": "object"
      },
      "EvaluationCreate": {
        "additionalProperties": false,
        "description": "Create a shadow integration study for registered actions with explicit success criteria.",
        "properties": {
          "action_keys": {
            "description": "Registered action keys included in the evaluation; the service deduplicates this selection.",
            "items": {
              "type": "string"
            },
            "maxItems": 100,
            "minItems": 1,
            "type": "array"
          },
          "ends_at": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Timezone-aware ISO 8601 study end, later than starts_at. Creation defaults to 30 days after the start; closing can shorten this cutoff."
          },
          "name": {
            "description": "Customer-visible display name for the action or evaluation.",
            "maxLength": 120,
            "type": "string"
          },
          "starts_at": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Timezone-aware ISO 8601 study start. If omitted during creation, the service uses the current time."
          },
          "success_criteria": {
            "$ref": "#/components/schemas/EvaluationCriteria",
            "description": "Recorded thresholds for shadow-decision count, abstention rate and outcome coverage, evaluated against the selected traces."
          }
        },
        "required": [
          "name",
          "action_keys"
        ],
        "title": "EvaluationCreate",
        "type": "object"
      },
      "EvaluationCriteria": {
        "additionalProperties": false,
        "description": "Thresholds for operational integration metrics used to evaluate the selected shadow decisions.",
        "properties": {
          "max_abstention_rate": {
            "default": 0.5,
            "description": "Maximum permitted fraction of selected decisions carrying decision.insufficient_evidence, from 0 to 1; default 0.5.",
            "maximum": 1.0,
            "minimum": 0.0,
            "type": "number"
          },
          "min_outcome_coverage": {
            "default": 0.5,
            "description": "Minimum fraction of selected decisions with recorded customer outcomes, from 0 to 1; default 0.5.",
            "maximum": 1.0,
            "minimum": 0.0,
            "type": "number"
          },
          "min_shadow_decisions": {
            "default": 50,
            "description": "Minimum number of selected shadow decisions; default 50.",
            "maximum": 1000000.0,
            "minimum": 1.0,
            "type": "integer"
          }
        },
        "title": "EvaluationCriteria",
        "type": "object"
      },
      "EvaluationMetrics": {
        "description": "Aggregated trace and customer-outcome metrics within the study window. Missing denominators can produce null ratios.",
        "properties": {
          "abstention_rate": {
            "anyOf": [
              {
                "type": "number"
              },
              {
                "type": "null"
              }
            ],
            "description": "Fraction of selected decisions carrying decision.insufficient_evidence, or null when the selection is empty."
          },
          "by_decision": {
            "additionalProperties": {
              "type": "integer"
            },
            "description": "Counts by decision label.",
            "type": "object"
          },
          "by_mode": {
            "additionalProperties": {
              "type": "integer"
            },
            "description": "Counts by action evaluation mode in the selected records.",
            "type": "object"
          },
          "challenges": {
            "description": "Count of selected decisions that requested a challenge.",
            "type": "integer"
          },
          "coverage_distribution": {
            "additionalProperties": {
              "type": "integer"
            },
            "description": "Counts by assurance coverage category.",
            "type": "object"
          },
          "decision_latency_ms": {
            "additionalProperties": {
              "anyOf": [
                {
                  "type": "integer"
                },
                {
                  "type": "null"
                }
              ]
            },
            "description": "Server decision latency summaries in milliseconds; entries may be null when no samples exist.",
            "type": "object"
          },
          "decisions": {
            "description": "Number of selected shadow authorization decisions.",
            "type": "integer"
          },
          "experimental_operator_change_indicators": {
            "description": "Number of selected decisions carrying the operator_change.detected indicator. Interpret with the sample and customer-reviewed outcomes.",
            "type": "integer"
          },
          "false_challenge_proxy": {
            "anyOf": [
              {
                "type": "number"
              },
              {
                "type": "null"
              }
            ],
            "description": "Fraction of challenge decisions whose reported outcome is executed or manually_approved, or null with no challenges. Review individual outcomes to assess whether the challenge was appropriate."
          },
          "note": {
            "description": "Interpretation limitations supplied with these operational metrics.",
            "type": "string"
          },
          "outcome_coverage": {
            "description": "Fraction of selected decisions with an outcome, from 0 to 1.",
            "type": "number"
          },
          "outcomes": {
            "additionalProperties": {
              "type": "integer"
            },
            "description": "Counts by customer-reported outcome label.",
            "type": "object"
          }
        },
        "required": [
          "decisions",
          "by_decision",
          "by_mode",
          "experimental_operator_change_indicators",
          "challenges",
          "coverage_distribution",
          "outcomes",
          "outcome_coverage",
          "decision_latency_ms",
          "note"
        ],
        "title": "EvaluationMetrics",
        "type": "object"
      },
      "EvaluationReport": {
        "description": "Evaluation configuration, current metrics and registered-criterion results.",
        "properties": {
          "action_keys": {
            "description": "Registered action keys included in the evaluation; the service deduplicates this selection.",
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "checks": {
            "additionalProperties": {
              "type": "boolean"
            },
            "description": "Per-criterion pass/fail results against the recorded thresholds.",
            "type": "object"
          },
          "created_at": {
            "description": "Creation time as an ISO 8601 timestamp.",
            "type": "string"
          },
          "ends_at": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Timezone-aware ISO 8601 study end, later than starts_at. Creation defaults to 30 days after the start; closing can shorten this cutoff."
          },
          "id": {
            "description": "Identifier of this record. Treat it as opaque and retain it for subsequent operations.",
            "type": "string"
          },
          "metrics": {
            "$ref": "#/components/schemas/EvaluationMetrics",
            "description": "Operational metrics computed from selected retained traces."
          },
          "name": {
            "description": "Customer-visible display name for the action or evaluation.",
            "type": "string"
          },
          "result": {
            "description": "passed when all recorded criteria are met; otherwise in_progress for an open study or failed for a closed study. An open study can pass before closure; close it to fix the cutoff.",
            "enum": [
              "in_progress",
              "passed",
              "failed"
            ],
            "type": "string"
          },
          "starts_at": {
            "description": "Timezone-aware ISO 8601 study start. If omitted during creation, the service uses the current time.",
            "type": "string"
          },
          "status": {
            "description": "Lifecycle state of this record; use the operation-specific values listed in the schema.",
            "enum": [
              "open",
              "closed"
            ],
            "type": "string"
          },
          "success_criteria": {
            "$ref": "#/components/schemas/EvaluationCriteria",
            "description": "Recorded thresholds for shadow-decision count, abstention rate and outcome coverage, evaluated against the selected traces."
          }
        },
        "required": [
          "id",
          "name",
          "action_keys",
          "success_criteria",
          "status",
          "starts_at",
          "created_at",
          "metrics",
          "checks",
          "result"
        ],
        "title": "EvaluationReport",
        "type": "object"
      },
      "EvidenceAck": {
        "description": "Receipt for one evidence window, including whether it contributed to accepted coverage.",
        "properties": {
          "active_seconds": {
            "description": "Duration of accepted active evidence in seconds.",
            "type": "number"
          },
          "coverage": {
            "description": "Evidence-coverage category: none, sparse, partial or sufficient. Describes the amount and variety of accepted evidence.",
            "enum": [
              "none",
              "sparse",
              "partial",
              "sufficient"
            ],
            "type": "string"
          },
          "enrollment_ready": {
            "default": false,
            "description": "Whether the server\u2019s accepted coverage meets enrollment readiness. Client elapsed time alone is insufficient.",
            "type": "boolean"
          },
          "evidence_windows": {
            "description": "Number of accepted, non-overlapping evidence windows accounted for in this session or profile.",
            "type": "integer"
          },
          "modalities_present": {
            "description": "Names of observed evidence modalities included in coverage accounting.",
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "reason_codes": {
            "description": "Stable reason identifiers explaining acceptance, limitations or a decision; resolve them in the reason-code catalog.",
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "status": {
            "description": "accepted contributes to coverage. Interpret neutral and rejected through the associated reason codes.",
            "enum": [
              "accepted",
              "neutral",
              "rejected"
            ],
            "type": "string"
          }
        },
        "required": [
          "status",
          "coverage",
          "evidence_windows",
          "active_seconds"
        ],
        "title": "EvidenceAck",
        "type": "object"
      },
      "FeatureFrameRequest": {
        "description": "A feature window submitted by the supported SDK, which handles extraction, session signing and transport.",
        "properties": {
          "duration_ms": {
            "description": "Frame duration in milliseconds; finite values from 0 through 600000 are accepted by the schema. Accepted coverage applies additional server checks.",
            "maximum": 600000.0,
            "minimum": 0.0,
            "type": "number"
          },
          "features": {
            "additionalProperties": true,
            "description": "SDK-produced modality feature object containing bounded derived features. Raw key content, images, video and audio stay outside the evidence submission.",
            "type": "object"
          },
          "frame_id": {
            "description": "Unique identifier for this frame within the session; repeated identifiers are refused by replay controls.",
            "maxLength": 128,
            "minLength": 1,
            "type": "string"
          },
          "purpose": {
            "default": "score",
            "description": "Frame purpose: enroll for enrollment evidence; score for observation. It must match the session\u2019s purpose.",
            "pattern": "^(score|enroll)$",
            "type": "string"
          },
          "research_optin": {
            "default": false,
            "description": "Separate per-frame JSON opt-in, default false. Retention requires this field plus current subject consent, environment participation and deployment eligibility.",
            "type": "boolean"
          },
          "timestamp": {
            "description": "Frame timestamp. The browser SDK emits Unix milliseconds; native-compatible Unix seconds are also normalized. Use the SDK\u2019s clock convention consistently.",
            "type": "number"
          },
          "window_end": {
            "anyOf": [
              {
                "minimum": 0.0,
                "type": "number"
              },
              {
                "type": "null"
              }
            ],
            "description": "Optional evidence-window end as Unix seconds. Bounds must describe a fresh, non-overlapping window for this session."
          },
          "window_start": {
            "anyOf": [
              {
                "minimum": 0.0,
                "type": "number"
              },
              {
                "type": "null"
              }
            ],
            "description": "Optional evidence-window start as Unix seconds. When omitted, bounds are derived from timestamp and duration_ms."
          }
        },
        "required": [
          "frame_id",
          "timestamp",
          "duration_ms",
          "features"
        ],
        "title": "FeatureFrameRequest",
        "type": "object"
      },
      "HumanReadable": {
        "description": "Customer-display wording explaining a decision; stable reason codes carry the programmatic meaning.",
        "properties": {
          "detail": {
            "description": "Human-readable explanation. Use stable codes and typed decision fields for application branching.",
            "type": "string"
          },
          "status": {
            "description": "Short display label for the decision; use reason codes for stable programmatic behavior.",
            "type": "string"
          }
        },
        "required": [
          "status",
          "detail"
        ],
        "title": "HumanReadable",
        "type": "object"
      },
      "ManualReviewRequest": {
        "additionalProperties": false,
        "description": "Record an attributed resolution for a held authorization.",
        "properties": {
          "note": {
            "anyOf": [
              {
                "maxLength": 500,
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Optional review note; retained as a digest rather than a free-text business record. Keep your review evidence in your own authorized system."
          },
          "resolution": {
            "description": "Attributed manual review result: approve or reject. Approval still requires a fresh verified child decision.",
            "enum": [
              "approve",
              "reject"
            ],
            "type": "string"
          }
        },
        "required": [
          "resolution"
        ],
        "title": "ManualReviewRequest",
        "type": "object"
      },
      "OutcomeReceipt": {
        "description": "Acknowledgment of the customer\u2019s recorded business-outcome label.",
        "properties": {
          "authorization": {
            "description": "Authorization identifier associated with this receipt. Resolve it on the backend and verify the bound proof before execution.",
            "type": "string"
          },
          "outcome": {
            "description": "Business outcome reported by the customer application, with supporting evidence maintained by the customer.",
            "type": "string"
          },
          "reported_at": {
            "description": "Time the outcome was recorded, as an ISO 8601 timestamp.",
            "type": "string"
          }
        },
        "required": [
          "authorization",
          "outcome",
          "reported_at"
        ],
        "title": "OutcomeReceipt",
        "type": "object"
      },
      "OutcomeReport": {
        "additionalProperties": false,
        "description": "Report what the customer application actually did after a decision; reporting never executes or authorizes the action.",
        "properties": {
          "note": {
            "anyOf": [
              {
                "maxLength": 500,
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Optional outcome note stored as a one-way digest. Keep a readable case narrative in your own application."
          },
          "outcome": {
            "description": "Business outcome reported by the customer application, with supporting evidence maintained by the customer.",
            "enum": [
              "executed",
              "not_executed",
              "manually_approved",
              "manually_rejected",
              "confirmed_attack",
              "false_challenge",
              "customer_override",
              "unknown"
            ],
            "type": "string"
          }
        },
        "required": [
          "outcome"
        ],
        "title": "OutcomeReport",
        "type": "object"
      },
      "PasskeyRegistered": {
        "description": "Identifier and creation time of the registered subject passkey.",
        "properties": {
          "created_at": {
            "description": "Creation time as an ISO 8601 timestamp.",
            "type": "string"
          },
          "id": {
            "description": "Identifier of this record. Treat it as opaque and retain it for subsequent operations.",
            "type": "string"
          }
        },
        "required": [
          "id",
          "created_at"
        ],
        "title": "PasskeyRegistered",
        "type": "object"
      },
      "PasskeyRegistrationGrant": {
        "description": "Single-use backend grant permitting the intended subject to begin passkey registration.",
        "properties": {
          "expires_at": {
            "description": "Expiry time as an ISO 8601 timestamp. Use the capability before this time; obtain a fresh one afterward.",
            "type": "string"
          },
          "token": {
            "description": "Short-lived, one-time passkey-registration grant. Deliver only to the authenticated subject\u2019s intended browser and keep out of logs.",
            "type": "string"
          }
        },
        "required": [
          "token",
          "expires_at"
        ],
        "title": "PasskeyRegistrationGrant",
        "type": "object"
      },
      "PasskeyRegistrationOptionsRequest": {
        "additionalProperties": false,
        "description": "Exchange a subject-bound one-time grant for WebAuthn registration options.",
        "properties": {
          "registration_grant": {
            "description": "One-time server-issued grant scoped to this subject\u2019s passkey registration.",
            "maxLength": 256,
            "minLength": 32,
            "type": "string"
          }
        },
        "required": [
          "registration_grant"
        ],
        "title": "PasskeyRegistrationOptionsRequest",
        "type": "object"
      },
      "PolicyRequirements": {
        "additionalProperties": false,
        "description": "Requirements and refusal precedence applied by one immutable policy version.",
        "properties": {
          "challenge_compensates": {
            "description": "Evidence shortfalls a completed challenge may compensate: operator_continuity, human_presence, coverage and freshness by default. Positive attack indicators remain subject to hold/deny rules.",
            "items": {
              "enum": [
                "operator_continuity",
                "human_presence",
                "coverage",
                "freshness"
              ],
              "type": "string"
            },
            "type": "array"
          },
          "challenge_methods": {
            "description": "Permitted compensating methods; default passkey. sandbox_confirm is sandbox-only simulation.",
            "items": {
              "enum": [
                "passkey",
                "sandbox_confirm"
              ],
              "type": "string"
            },
            "type": "array"
          },
          "claims": {
            "additionalProperties": {
              "type": "string"
            },
            "description": "Minimum status by claim name. The default requests operator_continuity at uncertain. Choose a requirement supported by the named claim.",
            "type": "object"
          },
          "coverage_min": {
            "default": "partial",
            "description": "Minimum accepted evidence coverage category; default partial.",
            "enum": [
              "none",
              "sparse",
              "partial",
              "sufficient"
            ],
            "type": "string"
          },
          "deny_on": {
            "description": "Reason codes that force deny under this policy. Default empty list.",
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "explicit_approval_required": {
            "default": false,
            "description": "Whether action-bound explicit approval is required even if other evidence satisfies policy.",
            "type": "boolean"
          },
          "freshness_max_ms": {
            "default": 60000,
            "description": "Maximum acceptable evidence age in milliseconds; default 60000 (one minute).",
            "maximum": 3600000.0,
            "minimum": 1000.0,
            "type": "integer"
          },
          "hold_on": {
            "description": "Reason codes that force hold under this policy. Default empty list.",
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "insufficient_evidence": {
            "default": "challenge",
            "description": "Decision used for insufficient evidence: challenge, hold or deny. Default challenge.",
            "enum": [
              "challenge",
              "hold",
              "deny"
            ],
            "type": "string"
          },
          "max_challenges": {
            "default": 2,
            "description": "Maximum challenges in one request chain before escalation to hold; default 2.",
            "maximum": 5.0,
            "minimum": 1.0,
            "type": "integer"
          }
        },
        "title": "PolicyRequirements",
        "type": "object"
      },
      "PolicyVersion": {
        "description": "Immutable decision contract and its draft, active or retired lifecycle state.",
        "properties": {
          "action": {
            "description": "Identifier of the protected-action record owning this version.",
            "type": "string"
          },
          "activated_at": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Policy activation time as an ISO 8601 timestamp, or null for a draft."
          },
          "allowed_audiences": {
            "description": "Relying-party audience identifiers allowed to receive proofs for this action.",
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "allowed_callers": {
            "description": "Credential identifiers allowed to authorize this action. An empty list permits any eligible server credential in the same environment.",
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "content_hash": {
            "description": "Digest of the immutable policy content; retain it when comparing policy configurations.",
            "type": "string"
          },
          "context_schema": {
            "additionalProperties": true,
            "description": "JSON Schema object applied to authorization context. Include every business value that must be bound to approval.",
            "type": "object"
          },
          "created_at": {
            "description": "Creation time as an ISO 8601 timestamp.",
            "type": "string"
          },
          "id": {
            "description": "Identifier of this record. Treat it as opaque and retain it for subsequent operations.",
            "type": "string"
          },
          "proof_ttl_seconds": {
            "description": "Proof lifetime in seconds, measured from issuance; the accepted range is 30-900 seconds.",
            "type": "integer"
          },
          "requirements": {
            "$ref": "#/components/schemas/PolicyRequirements",
            "description": "Assurance, freshness and challenge requirements evaluated by this policy version."
          },
          "retired_at": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Policy retirement time as an ISO 8601 timestamp, or null when not retired."
          },
          "status": {
            "description": "Lifecycle state of this record; use the operation-specific values listed in the schema.",
            "enum": [
              "draft",
              "active",
              "retired"
            ],
            "type": "string"
          },
          "version": {
            "description": "Monotonically assigned policy version number for the action.",
            "type": "integer"
          }
        },
        "required": [
          "id",
          "action",
          "version",
          "status",
          "requirements",
          "context_schema",
          "allowed_audiences",
          "allowed_callers",
          "proof_ttl_seconds",
          "content_hash",
          "created_at"
        ],
        "title": "PolicyVersion",
        "type": "object"
      },
      "PolicyVersionCreate": {
        "additionalProperties": false,
        "description": "Create a draft policy. Omitted optional security settings inherit from the active version; activation is a separate operation.",
        "properties": {
          "allowed_audiences": {
            "anyOf": [
              {
                "items": {
                  "type": "string"
                },
                "minItems": 1,
                "type": "array"
              },
              {
                "type": "null"
              }
            ],
            "description": "Relying-party audience identifiers allowed to receive proofs for this action."
          },
          "allowed_callers": {
            "anyOf": [
              {
                "items": {
                  "type": "string"
                },
                "type": "array"
              },
              {
                "type": "null"
              }
            ],
            "description": "Credential identifiers allowed to authorize this action. An empty list permits any eligible server credential in the same environment."
          },
          "context_schema": {
            "anyOf": [
              {
                "additionalProperties": true,
                "type": "object"
              },
              {
                "type": "null"
              }
            ],
            "description": "JSON Schema object applied to authorization context. Include every business value that must be bound to approval."
          },
          "proof_ttl_seconds": {
            "anyOf": [
              {
                "maximum": 900.0,
                "minimum": 30.0,
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "description": "Proof lifetime in seconds, measured from issuance; the accepted range is 30-900 seconds."
          },
          "requirements": {
            "$ref": "#/components/schemas/PolicyRequirements",
            "description": "Required complete requirement set for the new version; omitted fields inside it use the documented requirement defaults."
          }
        },
        "required": [
          "requirements"
        ],
        "title": "PolicyVersionCreate",
        "type": "object"
      },
      "Problem": {
        "description": "Canonical problem-details response. Inspect status and code; detail and title are explanatory text.",
        "properties": {
          "code": {
            "description": "Stable canonical error identifier used for integration behavior.",
            "type": "string"
          },
          "detail": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "Optional explanatory detail; wording is not a stable programmatic contract."
          },
          "instance": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "Optional identifier for this particular problem occurrence."
          },
          "status": {
            "description": "HTTP status code represented as an integer.",
            "type": "integer"
          },
          "title": {
            "description": "Short human-readable error summary.",
            "type": "string"
          },
          "type": {
            "default": "about:blank",
            "description": "Problem type URI; about:blank for the standard problem envelope.",
            "type": "string"
          }
        },
        "required": [
          "title",
          "status",
          "code"
        ],
        "title": "Problem",
        "type": "object"
      },
      "ProofStatus": {
        "description": "Current scoped server state for a proof identifier. Use proof verification and consumption before execution.",
        "properties": {
          "expires_at": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Expiry time as an ISO 8601 timestamp. Use the capability before this time; obtain a fresh one afterward."
          },
          "jti": {
            "description": "Proof identifier from a verified proof or trusted authorization trace.",
            "type": "string"
          },
          "revoked_at": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Revocation time as an ISO 8601 timestamp, or null when not revoked."
          },
          "status": {
            "description": "active, consumed, revoked, expired or unknown. Only active is eligible for attempted consumption.",
            "enum": [
              "active",
              "consumed",
              "revoked",
              "expired",
              "unknown"
            ],
            "type": "string"
          }
        },
        "required": [
          "jti",
          "status"
        ],
        "title": "ProofStatus",
        "type": "object"
      },
      "ProofTrace": {
        "description": "Signed proof and current state associated with an authorization trace.",
        "properties": {
          "compact": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Compact JWS when available; keep it out of logs and browser-controlled execution decisions."
          },
          "expires_at": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Expiry time as an ISO 8601 timestamp. Use the capability before this time; obtain a fresh one afterward."
          },
          "id": {
            "description": "Identifier of this record. Treat it as opaque and retain it for subsequent operations.",
            "type": "string"
          },
          "status": {
            "description": "Lifecycle state of this record; use the operation-specific values listed in the schema.",
            "type": "string"
          }
        },
        "required": [
          "id",
          "status"
        ],
        "title": "ProofTrace",
        "type": "object"
      },
      "ProtectedAction": {
        "description": "Protected-action metadata together with the currently selected policy settings and evaluation mode.",
        "properties": {
          "active_policy_version": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "description": "Currently active policy version number, or null when no version is active."
          },
          "allowed_audiences": {
            "description": "Relying-party audience identifiers allowed to receive proofs for this action.",
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "allowed_callers": {
            "description": "Credential identifiers allowed to authorize this action. An empty list permits any eligible server credential in the same environment.",
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "consequence": {
            "description": "Plain-language consequence if the wrong person performs the protected action.",
            "type": "string"
          },
          "context_schema": {
            "additionalProperties": true,
            "description": "JSON Schema object applied to authorization context. Include every business value that must be bound to approval.",
            "type": "object"
          },
          "created_at": {
            "description": "Creation time as an ISO 8601 timestamp.",
            "type": "string"
          },
          "environment": {
            "description": "Environment identifier that scopes this record; sandbox and live resources are separate.",
            "type": "string"
          },
          "id": {
            "description": "Identifier of this record. Treat it as opaque and retain it for subsequent operations.",
            "type": "string"
          },
          "key": {
            "description": "Stable dotted action key used by authorization, such as payout.destination.change.",
            "type": "string"
          },
          "mode": {
            "description": "Action evaluation mode. Test and shadow return decisions without enforceable proofs. An eligible enforce-mode allow can carry a proof.",
            "enum": [
              "test",
              "shadow",
              "enforce"
            ],
            "type": "string"
          },
          "name": {
            "description": "Customer-visible display name for the action or evaluation.",
            "type": "string"
          },
          "proof_ttl_seconds": {
            "description": "Proof lifetime in seconds, measured from issuance; the accepted range is 30-900 seconds.",
            "type": "integer"
          },
          "resource_type": {
            "description": "Customer-defined category of the protected resource, such as merchant.",
            "type": "string"
          },
          "risk_class": {
            "description": "Customer-selected consequence category for the action: low, elevated, high or critical.",
            "enum": [
              "low",
              "elevated",
              "high",
              "critical"
            ],
            "type": "string"
          },
          "updated_at": {
            "description": "Most recent update time as an ISO 8601 timestamp.",
            "type": "string"
          }
        },
        "required": [
          "id",
          "environment",
          "key",
          "name",
          "consequence",
          "risk_class",
          "resource_type",
          "context_schema",
          "mode",
          "allowed_audiences",
          "allowed_callers",
          "proof_ttl_seconds",
          "created_at",
          "updated_at"
        ],
        "title": "ProtectedAction",
        "type": "object"
      },
      "RecoveryBegin": {
        "additionalProperties": false,
        "description": "Start re-enrollment for a revoked subject under its configured recovery policy.",
        "properties": {
          "anchor": {
            "description": "Account anchor established by the customer identity process and recorded by GrayPass.",
            "enum": [
              "none",
              "customer_session",
              "idp",
              "passkey",
              "verified_identity"
            ],
            "type": "string"
          },
          "anchor_evidence_ref": {
            "anyOf": [
              {
                "maxLength": 256,
                "minLength": 8,
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Reference to the customer\u2019s anchor evidence; required for idp, passkey and verified_identity anchors. The customer identity process establishes the underlying claim. GrayPass retains the digest without independently verifying that identity claim."
          }
        },
        "required": [
          "anchor"
        ],
        "title": "RecoveryBegin",
        "type": "object"
      },
      "ResearchConsentRequest": {
        "additionalProperties": false,
        "description": "Record or revoke subject research consent separately from ordinary service use and subject creation.",
        "properties": {
          "consented": {
            "description": "Strict JSON boolean: true records consent and false records withdrawal. The server fixes the receipt purpose and disclosure version. Deployment eligibility is configured separately.",
            "type": "boolean"
          }
        },
        "required": [
          "consented"
        ],
        "title": "ResearchConsentRequest",
        "type": "object"
      },
      "Resource": {
        "additionalProperties": false,
        "description": "Exact business resource bound to an authorization.",
        "properties": {
          "id": {
            "description": "Application resource identifier, derived from the authenticated pending business request.",
            "maxLength": 256,
            "minLength": 1,
            "type": "string"
          },
          "type": {
            "description": "Application resource category, such as merchant.",
            "maxLength": 64,
            "minLength": 1,
            "type": "string"
          }
        },
        "required": [
          "type",
          "id"
        ],
        "title": "Resource",
        "type": "object"
      },
      "ReviewApprovedReceipt": {
        "description": "Approved review receipt with a newly evaluated child decision. Inspect that decision and complete its required verification before execution.",
        "properties": {
          "authorization": {
            "description": "Authorization identifier associated with this receipt. Resolve it on the backend and verify the bound proof before execution.",
            "type": "string"
          },
          "decision": {
            "$ref": "#/components/schemas/AuthorizeResponse",
            "description": "Fresh child authorization response, requiring the usual parent, request binding and proof checks."
          },
          "resolution": {
            "const": "approve",
            "description": "Attributed manual review result: approve or reject. Approval still requires a fresh verified child decision.",
            "type": "string"
          }
        },
        "required": [
          "authorization",
          "resolution",
          "decision"
        ],
        "title": "ReviewApprovedReceipt",
        "type": "object"
      },
      "ReviewRejectedReceipt": {
        "description": "Rejected manual-review receipt and its recorded rejection outcome.",
        "properties": {
          "authorization": {
            "description": "Authorization identifier associated with this receipt. Resolve it on the backend and verify the bound proof before execution.",
            "type": "string"
          },
          "outcome": {
            "$ref": "#/components/schemas/OutcomeReceipt",
            "description": "Outcome receipt for the manual rejection."
          },
          "resolution": {
            "const": "reject",
            "description": "Attributed manual review result: approve or reject. Approval still requires a fresh verified child decision.",
            "type": "string"
          }
        },
        "required": [
          "authorization",
          "resolution",
          "outcome"
        ],
        "title": "ReviewRejectedReceipt",
        "type": "object"
      },
      "SessionCreate": {
        "additionalProperties": false,
        "description": "Open an enrollment or observation session for the authenticated subject.",
        "properties": {
          "device_context": {
            "anyOf": [
              {
                "additionalProperties": true,
                "type": "object"
              },
              {
                "type": "null"
              }
            ],
            "description": "Optional customer-provided device context, without independent device integrity attestation. Apply your endpoint controls to establish device trust."
          },
          "purpose": {
            "default": "observe",
            "description": "enroll collects enrollment evidence; observe assesses continuity. The default is observe.",
            "enum": [
              "observe",
              "enroll"
            ],
            "type": "string"
          },
          "subject": {
            "description": "Pseudonymous subject identifier in the authenticated tenant and environment.",
            "type": "string"
          }
        },
        "required": [
          "subject"
        ],
        "title": "SessionCreate",
        "type": "object"
      },
      "SessionCreated": {
        "description": "Session identifier, feature contract and short-lived evidence-signing material returned to its scoped caller.",
        "properties": {
          "created_at": {
            "description": "Creation time as an ISO 8601 timestamp.",
            "type": "string"
          },
          "feature_schema_version": {
            "description": "Version identifier for the feature representation used by the session or assessment.",
            "type": "string"
          },
          "frame_signing_alg": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Algorithm identifier for the session\u2019s evidence-signing material."
          },
          "frame_signing_key": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Session-specific signing secret for SDK evidence transport, when issued. Never log or expose it to another subject."
          },
          "id": {
            "description": "Identifier of this record. Treat it as opaque and retain it for subsequent operations.",
            "type": "string"
          },
          "purpose": {
            "description": "Session purpose, enroll or observe.",
            "type": "string"
          },
          "research_enabled": {
            "default": false,
            "description": "Environment participation and a current subject consent receipt are both present at session creation. Storage also requires deployment enablement, current consent and per-frame opt-in.",
            "type": "boolean"
          },
          "subject": {
            "description": "Pseudonymous subject identifier in the authenticated tenant and environment.",
            "type": "string"
          }
        },
        "required": [
          "id",
          "subject",
          "purpose",
          "feature_schema_version",
          "created_at"
        ],
        "title": "SessionCreated",
        "type": "object"
      },
      "SessionEnded": {
        "description": "Receipt for an ended evidence session and its accounted duration and windows.",
        "properties": {
          "duration_seconds": {
            "description": "Elapsed session duration in seconds, distinct from accepted active evidence duration.",
            "minimum": 0.0,
            "type": "number"
          },
          "evidence_windows": {
            "description": "Number of accepted, non-overlapping evidence windows accounted for in this session or profile.",
            "minimum": 0.0,
            "type": "integer"
          },
          "session": {
            "description": "Observation or enrollment session identifier, as required by the operation.",
            "type": "string"
          },
          "status": {
            "const": "ended",
            "description": "Lifecycle state of this record; use the operation-specific values listed in the schema.",
            "type": "string"
          }
        },
        "required": [
          "session",
          "status",
          "duration_seconds",
          "evidence_windows"
        ],
        "title": "SessionEnded",
        "type": "object"
      },
      "StatusSummary": {
        "description": "Browser-safe coverage and enrollment-readiness summary without a score or full server assessment.",
        "properties": {
          "active_seconds": {
            "description": "Duration of accepted active evidence in seconds.",
            "type": "number"
          },
          "coverage": {
            "description": "Evidence-coverage category: none, sparse, partial or sufficient. Describes the amount and variety of accepted evidence.",
            "enum": [
              "none",
              "sparse",
              "partial",
              "sufficient"
            ],
            "type": "string"
          },
          "enrollment_ready": {
            "default": false,
            "description": "Whether the server\u2019s accepted coverage meets enrollment readiness. Client elapsed time alone is insufficient.",
            "type": "boolean"
          },
          "evidence_windows": {
            "description": "Number of accepted, non-overlapping evidence windows accounted for in this session or profile.",
            "type": "integer"
          },
          "freshness_ms": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "description": "Age of the relevant evidence in milliseconds; null when freshness cannot be established."
          },
          "human_readable": {
            "description": "Human-readable coverage/readiness explanation for the user interface.",
            "type": "string"
          },
          "limitations": {
            "description": "Applicable limitations that must accompany interpretation of the result.",
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "modalities_present": {
            "description": "Names of observed evidence modalities included in coverage accounting.",
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "session": {
            "description": "Observation or enrollment session identifier, as required by the operation.",
            "type": "string"
          }
        },
        "required": [
          "session",
          "coverage",
          "evidence_windows",
          "active_seconds",
          "freshness_ms",
          "human_readable"
        ],
        "title": "StatusSummary",
        "type": "object"
      },
      "Subject": {
        "description": "Pseudonymous subject lifecycle record within one environment.",
        "properties": {
          "adaptation_frozen": {
            "description": "Whether online template adaptation is frozen; true prevents silent template adaptation.",
            "type": "boolean"
          },
          "anchor": {
            "description": "Account anchor established by the customer identity process and recorded by GrayPass.",
            "type": "string"
          },
          "created_at": {
            "description": "Creation time as an ISO 8601 timestamp.",
            "type": "string"
          },
          "enrollment_state": {
            "description": "Current enrollment lifecycle state. Revoked subjects need the configured recovery path; deleted subjects are no longer operationally retrievable.",
            "enum": [
              "not_enrolled",
              "enrolling",
              "enrolled",
              "revoked",
              "deleted"
            ],
            "type": "string"
          },
          "environment": {
            "description": "Environment identifier that scopes this record; sandbox and live resources are separate.",
            "type": "string"
          },
          "id": {
            "description": "Identifier of this record. Treat it as opaque and retain it for subsequent operations.",
            "type": "string"
          },
          "limitations": {
            "description": "Applicable limitations that must accompany interpretation of the result.",
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "recovery_policy": {
            "description": "Recovery rule governing whether re-enrollment requires an anchor or a separate manual-review process.",
            "type": "string"
          },
          "revoked_at": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Revocation time as an ISO 8601 timestamp, or null when not revoked."
          }
        },
        "required": [
          "id",
          "environment",
          "enrollment_state",
          "anchor",
          "recovery_policy",
          "adaptation_frozen",
          "created_at"
        ],
        "title": "Subject",
        "type": "object"
      },
      "SubjectCreate": {
        "additionalProperties": false,
        "description": "Create or retrieve the subject mapped to a stable customer reference and compatible security settings.",
        "properties": {
          "anchor": {
            "default": "customer_session",
            "description": "Account anchor established by the customer identity process and recorded by GrayPass.",
            "enum": [
              "none",
              "customer_session",
              "idp",
              "passkey",
              "verified_identity"
            ],
            "type": "string"
          },
          "anchor_evidence_ref": {
            "anyOf": [
              {
                "maxLength": 256,
                "minLength": 8,
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Reference to the customer\u2019s anchor evidence; required for idp, passkey and verified_identity anchors. The customer identity process establishes the underlying claim. GrayPass retains the digest without independently verifying that identity claim."
          },
          "external_ref": {
            "description": "Stable customer account reference, 1-256 characters. It is received by the API and retained as a keyed hash; avoid using direct personal information.",
            "maxLength": 256,
            "minLength": 1,
            "type": "string"
          },
          "metadata": {
            "additionalProperties": true,
            "description": "Optional customer metadata object. This version retains only the label key; avoid sensitive information.",
            "type": "object"
          },
          "recovery_policy": {
            "default": "re_enroll_with_anchor",
            "description": "Recovery rule governing whether re-enrollment requires an anchor or a separate manual-review process.",
            "enum": [
              "re_enroll_with_anchor",
              "re_enroll_any",
              "manual_review"
            ],
            "type": "string"
          }
        },
        "required": [
          "external_ref"
        ],
        "title": "SubjectCreate",
        "type": "object"
      },
      "VerifyRequest": {
        "additionalProperties": false,
        "description": "Online verification against expected action binding, with optional atomic one-time consumption.",
        "properties": {
          "audience": {
            "description": "Expected relying-party audience. It must be permitted by the action and independently known to the verifier.",
            "type": "string"
          },
          "consume": {
            "default": false,
            "description": "Default false performs a state check. Set true immediately before the protected operation to attempt one-time consumption; it is a separate transaction from your business database.",
            "type": "boolean"
          },
          "expected_action": {
            "description": "Action key independently retained with the pending business request.",
            "type": "string"
          },
          "expected_action_hash": {
            "description": "64-character SHA-256 hex action hash computed from the original server-held material, never learned from an unverified proof.",
            "maxLength": 64,
            "minLength": 64,
            "type": "string"
          },
          "proof": {
            "description": "Compact JWS obtained through your trusted authorization workflow. First perform the documented offline and subject/tenant/environment binding checks.",
            "type": "string"
          }
        },
        "required": [
          "proof",
          "audience",
          "expected_action",
          "expected_action_hash"
        ],
        "title": "VerifyRequest",
        "type": "object"
      },
      "VerifyResponse": {
        "description": "Verification result. HTTP 200 can still mean valid is false; never authorize based on transport status alone.",
        "properties": {
          "claims": {
            "anyOf": [
              {
                "additionalProperties": true,
                "type": "object"
              },
              {
                "type": "null"
              }
            ],
            "description": "Verified proof claims when valid, otherwise null. Compare them with the application\u2019s independent expectations."
          },
          "reason": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Stable verification refusal reason when invalid, otherwise null."
          },
          "valid": {
            "description": "True only when all online checks succeed and, if requested, one-time consumption succeeds.",
            "type": "boolean"
          }
        },
        "required": [
          "valid"
        ],
        "title": "VerifyResponse",
        "type": "object"
      }
    },
    "securitySchemes": {
      "HTTPBearer": {
        "description": "Bearer server credential for backend operations, or a scoped short-lived browser token only where the operation permits it.",
        "scheme": "bearer",
        "type": "http"
      }
    }
  },
  "info": {
    "description": "Canonical JSON API for subject lifecycle, evidence sessions, action-bound authorization, proof verification and evaluations.",
    "title": "GrayPass API",
    "version": "2026-10-01"
  },
  "openapi": "3.1.0",
  "paths": {
    "/.well-known/graypass-proof-keys.json": {
      "get": {
        "description": "Fetch the public keys used for Proof of Agency signature verification from the configured trusted service.",
        "operationId": "proof_jwks__well_known_graypass_proof_keys_json_get",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "keys": []
                },
                "schema": {
                  "additionalProperties": true,
                  "type": "object"
                }
              }
            },
            "description": "JSON Web Key Set with public verification keys. Verification requires the key matching the proof\u2019s kid."
          }
        },
        "summary": "Read public proof verification keys",
        "tags": [
          "public"
        ]
      }
    },
    "/api/v1/actions": {
      "get": {
        "description": "Read non-archived action definitions in this environment.",
        "operationId": "list_actions_api_v1_actions_get",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "items": {
                    "$ref": "#/components/schemas/ProtectedAction"
                  },
                  "type": "array"
                }
              }
            },
            "description": "Array of up to 500 non-archived protected actions."
          }
        },
        "security": [
          {
            "HTTPBearer": []
          }
        ],
        "summary": "List protected actions",
        "tags": [
          "canonical"
        ]
      },
      "post": {
        "description": "Create an action definition and its initial active policy in shadow mode.",
        "operationId": "create_action_api_v1_actions_post",
        "requestBody": {
          "content": {
            "application/json": {
              "example": {
                "allowed_audiences": [
                  "merchant-api"
                ],
                "consequence": "Future payouts may be sent to a different destination.",
                "context_schema": {
                  "additionalProperties": false,
                  "properties": {
                    "destination_fingerprint": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "destination_fingerprint"
                  ],
                  "type": "object"
                },
                "key": "payout.destination.change",
                "name": "Change payout destination",
                "resource_type": "merchant"
              },
              "schema": {
                "$ref": "#/components/schemas/ActionCreate"
              }
            }
          },
          "description": "Supply a dotted key, display name, consequence and nonempty allowed_audiences. Use context_schema to bind sensitive business fields.",
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProtectedAction"
                }
              }
            },
            "description": "ProtectedAction in shadow mode with its initial active policy version."
          },
          "422": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            },
            "description": "The canonical handler returns a Problem for invalid input; correct the request before retrying."
          }
        },
        "security": [
          {
            "HTTPBearer": []
          }
        ],
        "summary": "Register a protected action",
        "tags": [
          "canonical"
        ]
      }
    },
    "/api/v1/actions/{action_id}": {
      "delete": {
        "description": "Stop using an action through the normal active action surface while retaining its historical records.",
        "operationId": "archive_action_api_v1_actions__action_id__delete",
        "parameters": [
          {
            "description": "Protected-action record identifier returned by action creation. Supply this record ID in the path; use the dotted action key in authorization requests.",
            "in": "path",
            "name": "action_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Action archival completed; the 204 response has no body."
          },
          "422": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            },
            "description": "The canonical handler returns a Problem for invalid input; correct the request before retrying."
          }
        },
        "security": [
          {
            "HTTPBearer": []
          }
        ],
        "summary": "Archive a protected action",
        "tags": [
          "canonical"
        ]
      },
      "get": {
        "description": "Inspect the action\u2019s display metadata, mode and active policy settings before integration or a configuration change.",
        "operationId": "get_action_api_v1_actions__action_id__get",
        "parameters": [
          {
            "description": "Protected-action record identifier returned by action creation. Supply this record ID in the path; use the dotted action key in authorization requests.",
            "in": "path",
            "name": "action_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProtectedAction"
                }
              }
            },
            "description": "ProtectedAction with mode and effective active policy settings."
          },
          "422": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            },
            "description": "The canonical handler returns a Problem for invalid input; correct the request before retrying."
          }
        },
        "security": [
          {
            "HTTPBearer": []
          }
        ],
        "summary": "Read a protected action",
        "tags": [
          "canonical"
        ]
      },
      "patch": {
        "description": "Change an action\u2019s customer-facing name, consequence or test/shadow/enforce mode.",
        "operationId": "update_action_api_v1_actions__action_id__patch",
        "parameters": [
          {
            "description": "Protected-action record identifier returned by action creation. Supply this record ID in the path; use the dotted action key in authorization requests.",
            "in": "path",
            "name": "action_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "example": {
                "name": "Change merchant payout destination"
              },
              "schema": {
                "$ref": "#/components/schemas/ActionUpdate"
              }
            }
          },
          "description": "Omit fields that should remain unchanged. Change audiences, caller restrictions, context or proof lifetime through a new policy version.",
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProtectedAction"
                }
              }
            },
            "description": "Updated ProtectedAction metadata and current mode."
          },
          "422": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            },
            "description": "The canonical handler returns a Problem for invalid input; correct the request before retrying."
          }
        },
        "security": [
          {
            "HTTPBearer": []
          }
        ],
        "summary": "Update action metadata or mode",
        "tags": [
          "canonical"
        ]
      }
    },
    "/api/v1/actions/{action_id}/policy-versions": {
      "get": {
        "description": "Inspect the action\u2019s immutable draft, active and retired policy snapshots.",
        "operationId": "list_policy_versions_api_v1_actions__action_id__policy_versions_get",
        "parameters": [
          {
            "description": "Protected-action record identifier returned by action creation. Supply this record ID in the path; use the dotted action key in authorization requests.",
            "in": "path",
            "name": "action_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "items": {
                    "$ref": "#/components/schemas/PolicyVersion"
                  },
                  "type": "array"
                }
              }
            },
            "description": "Array of bounded policy snapshots with version numbers and lifecycle states."
          },
          "422": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            },
            "description": "The canonical handler returns a Problem for invalid input; correct the request before retrying."
          }
        },
        "security": [
          {
            "HTTPBearer": []
          }
        ],
        "summary": "List action policy versions",
        "tags": [
          "canonical"
        ]
      },
      "post": {
        "description": "Prepare a new immutable policy snapshot without activating it.",
        "operationId": "create_policy_version_api_v1_actions__action_id__policy_versions_post",
        "parameters": [
          {
            "description": "Protected-action record identifier returned by action creation. Supply this record ID in the path; use the dotted action key in authorization requests.",
            "in": "path",
            "name": "action_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "example": {
                "requirements": {
                  "challenge_methods": [
                    "passkey"
                  ],
                  "coverage_min": "partial",
                  "freshness_max_ms": 60000,
                  "insufficient_evidence": "challenge"
                }
              },
              "schema": {
                "$ref": "#/components/schemas/PolicyVersionCreate"
              }
            }
          },
          "description": "requirements is required. Omitted optional audiences, caller restrictions, context schema and proof lifetime inherit from the active version.",
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PolicyVersion"
                }
              }
            },
            "description": "New immutable draft policy and its assigned version number."
          },
          "422": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            },
            "description": "The canonical handler returns a Problem for invalid input; correct the request before retrying."
          }
        },
        "security": [
          {
            "HTTPBearer": []
          }
        ],
        "summary": "Create a draft policy version",
        "tags": [
          "canonical"
        ]
      }
    },
    "/api/v1/actions/{action_id}/policy-versions/{version}/activate": {
      "post": {
        "description": "Select an existing version as the action\u2019s active decision contract.",
        "operationId": "activate_policy_version_api_v1_actions__action_id__policy_versions__version__activate_post",
        "parameters": [
          {
            "description": "Protected-action record identifier returned by action creation. Supply this record ID in the path; use the dotted action key in authorization requests.",
            "in": "path",
            "name": "action_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Policy version number belonging to the action. Supply the numeric version in this path.",
            "in": "path",
            "name": "version",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PolicyVersion"
                }
              }
            },
            "description": "Selected policy version in active state."
          },
          "422": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            },
            "description": "The canonical handler returns a Problem for invalid input; correct the request before retrying."
          }
        },
        "security": [
          {
            "HTTPBearer": []
          }
        ],
        "summary": "Activate a reviewed policy version",
        "tags": [
          "canonical"
        ]
      }
    },
    "/api/v1/activity": {
      "get": {
        "description": "Find recent authorization traces by action, decision or subject for operational diagnosis.",
        "operationId": "activity_api_v1_activity_get",
        "parameters": [
          {
            "description": "Maximum records requested; default 100. The service bounds it to 1-500. No cursor pagination is exposed.",
            "in": "query",
            "name": "limit",
            "required": false,
            "schema": {
              "default": 100,
              "type": "integer"
            }
          },
          {
            "description": "Optional exact dotted action-key filter.",
            "in": "query",
            "name": "action_key",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ]
            }
          },
          {
            "description": "Optional exact decision filter, normally allow, challenge, hold or deny.",
            "in": "query",
            "name": "decision",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ]
            }
          },
          {
            "description": "Subject identifier resolved from your authenticated account mapping.",
            "in": "query",
            "name": "subject_id",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "items": {
                    "$ref": "#/components/schemas/AuthorizationTrace"
                  },
                  "type": "array"
                }
              }
            },
            "description": "Recent authorization traces matching the supplied exact filters, newest decision first."
          },
          "422": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            },
            "description": "The canonical handler returns a Problem for invalid input; correct the request before retrying."
          }
        },
        "security": [
          {
            "HTTPBearer": []
          }
        ],
        "summary": "List authorization activity",
        "tags": [
          "canonical"
        ]
      }
    },
    "/api/v1/authorizations/{authorization_id}": {
      "get": {
        "description": "Retrieve the stored authorization identified by the request path. To resolve a challenge or review child, fetch the resulting child authorization ID explicitly.",
        "operationId": "get_authorization_api_v1_authorizations__authorization_id__get",
        "parameters": [
          {
            "description": "Authorization identifier returned by a prior request or trusted challenge receipt.",
            "in": "path",
            "name": "authorization_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuthorizationTrace"
                }
              }
            },
            "description": "Full trace including original binding, parent relation and nested challenge/proof/review/outcome state."
          },
          "422": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            },
            "description": "The canonical handler returns a Problem for invalid input; correct the request before retrying."
          }
        },
        "security": [
          {
            "HTTPBearer": []
          }
        ],
        "summary": "Read an authorization trace",
        "tags": [
          "canonical"
        ]
      }
    },
    "/api/v1/authorizations/{authorization_id}/outcome": {
      "post": {
        "description": "Record the outcome actually observed by the customer application after a decision.",
        "operationId": "report_outcome_api_v1_authorizations__authorization_id__outcome_post",
        "parameters": [
          {
            "description": "Authorization identifier returned by a prior request or trusted challenge receipt.",
            "in": "path",
            "name": "authorization_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "example": {
                "outcome": "not_executed"
              },
              "schema": {
                "$ref": "#/components/schemas/OutcomeReport"
              }
            }
          },
          "description": "Choose the declared outcome label. Optional note is retained as a digest; use a minimal, non-confidential reference.",
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "authorization": "az_example",
                  "outcome": "not_executed",
                  "reported_at": "2026-10-01T12:00:00Z"
                },
                "schema": {
                  "$ref": "#/components/schemas/OutcomeReceipt"
                }
              }
            },
            "description": "Recorded authorization id, outcome label and report timestamp."
          },
          "422": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            },
            "description": "The canonical handler returns a Problem for invalid input; correct the request before retrying."
          }
        },
        "security": [
          {
            "HTTPBearer": []
          }
        ],
        "summary": "Record the business outcome",
        "tags": [
          "canonical"
        ]
      }
    },
    "/api/v1/authorizations/{authorization_id}/review": {
      "post": {
        "description": "Record an attributed administrator approve/reject resolution for manual review.",
        "operationId": "review_authorization_api_v1_authorizations__authorization_id__review_post",
        "parameters": [
          {
            "description": "Authorization identifier returned by a prior request or trusted challenge receipt.",
            "in": "path",
            "name": "authorization_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "example": {
                "resolution": "reject"
              },
              "schema": {
                "$ref": "#/components/schemas/ManualReviewRequest"
              }
            }
          },
          "description": "Use the held authorization id. resolution is approve or reject; note is optional and retained as a digest.",
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "authorization": "az_example",
                  "outcome": {
                    "authorization": "az_example",
                    "outcome": "manually_rejected",
                    "reported_at": "2026-10-01T12:00:00Z"
                  },
                  "resolution": "reject"
                },
                "schema": {
                  "anyOf": [
                    {
                      "$ref": "#/components/schemas/ReviewApprovedReceipt"
                    },
                    {
                      "$ref": "#/components/schemas/ReviewRejectedReceipt"
                    }
                  ]
                }
              }
            },
            "description": "Reject returns an outcome receipt; approve returns a fresh child decision that may still refuse execution."
          },
          "422": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            },
            "description": "The canonical handler returns a Problem for invalid input; correct the request before retrying."
          }
        },
        "security": [
          {
            "HTTPBearer": []
          }
        ],
        "summary": "Resolve a held authorization",
        "tags": [
          "canonical"
        ]
      }
    },
    "/api/v1/authorize": {
      "post": {
        "description": "Evaluate one immutable request against the action\u2019s active policy and return allow, challenge, hold or deny.",
        "operationId": "authorize_api_v1_authorize_post",
        "requestBody": {
          "content": {
            "application/json": {
              "example": {
                "action": "payout.destination.change",
                "actor": {
                  "id": "sub_example",
                  "type": "human"
                },
                "audience": "merchant-api",
                "context": {
                  "destination_fingerprint": "bank-destination-fingerprint-7"
                },
                "idempotency_key": "payout-change-42-request-7",
                "nonce": "2de95a66-712e-4a60-9ccf-3c9b53e442fa",
                "requested_at": 1790856000,
                "resource": {
                  "id": "merchant_42",
                  "type": "merchant"
                },
                "session": "ses_example",
                "subject": "sub_example"
              },
              "schema": {
                "$ref": "#/components/schemas/AuthorizeRequest"
              }
            }
          },
          "description": "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.",
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "action": "payout.destination.change",
                  "action_hash": "15ffd65a68fe273d7982c94152aa6e974e4f4b182e1733cc96fed169cfec22ea",
                  "assurance": {
                    "active_seconds": 0.0,
                    "assessed_at": "2026-10-01T12:00:00Z",
                    "claims": [],
                    "coverage": "none",
                    "evidence_windows": 0,
                    "feature_schema_version": "example-feature-version",
                    "freshness_ms": null,
                    "id": "asr_example",
                    "insufficient_evidence": true,
                    "limitations": [
                      "insufficient evidence"
                    ],
                    "modalities_present": [],
                    "model_version": "example-model-version",
                    "rule_version": "example-rule-version",
                    "session": "ses_example",
                    "subject": "sub_example"
                  },
                  "challenge": {
                    "expires_at": "2026-10-01T12:05:00Z",
                    "id": "ch_example",
                    "methods": [
                      "passkey"
                    ]
                  },
                  "decided_at": "2026-10-01T12:00:00Z",
                  "decision": "challenge",
                  "environment": "env_example",
                  "human_readable": {
                    "detail": "Additional action-bound confirmation is required.",
                    "status": "challenge"
                  },
                  "id": "az_example",
                  "latency_ms": 12,
                  "mode": "shadow",
                  "policy_version": 1,
                  "proof": null,
                  "proof_id": null,
                  "reason_codes": [
                    "decision.insufficient_evidence"
                  ],
                  "trace_id": "az_example"
                },
                "schema": {
                  "$ref": "#/components/schemas/AuthorizeResponse"
                }
              }
            },
            "description": "Decision, mode, independent-binding digest, policy version, reasons and Assurance Profile; challenge or proof appears only when applicable."
          },
          "422": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            },
            "description": "The canonical handler returns a Problem for invalid input; correct the request before retrying."
          }
        },
        "security": [
          {
            "HTTPBearer": []
          }
        ],
        "summary": "Evaluate a bound business request",
        "tags": [
          "canonical"
        ]
      }
    },
    "/api/v1/challenges/{challenge_id}": {
      "get": {
        "description": "Retrieve a challenge\u2019s current state, permitted methods, expiry and action display for explicit confirmation.",
        "operationId": "get_challenge_api_v1_challenges__challenge_id__get",
        "parameters": [
          {
            "description": "Challenge identifier tied to the original pending authorization.",
            "in": "path",
            "name": "challenge_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ChallengePublicView"
                }
              }
            },
            "description": "Current challenge state, available methods, expiry and browser-safe action display."
          },
          "422": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            },
            "description": "The canonical handler returns a Problem for invalid input; correct the request before retrying."
          }
        },
        "security": [
          {
            "HTTPBearer": []
          }
        ],
        "summary": "Read a scoped challenge",
        "tags": [
          "canonical"
        ]
      }
    },
    "/api/v1/challenges/{challenge_id}/cancel": {
      "post": {
        "description": "Refuse the offered action confirmation and stop that pending challenge from completing.",
        "operationId": "cancel_challenge_api_v1_challenges__challenge_id__cancel_post",
        "parameters": [
          {
            "description": "Challenge identifier tied to the original pending authorization.",
            "in": "path",
            "name": "challenge_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "id": "ch_example",
                  "status": "cancelled"
                },
                "schema": {
                  "$ref": "#/components/schemas/ChallengeCancelled"
                }
              }
            },
            "description": "Challenge id and cancelled status."
          },
          "422": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            },
            "description": "The canonical handler returns a Problem for invalid input; correct the request before retrying."
          }
        },
        "security": [
          {
            "HTTPBearer": []
          }
        ],
        "summary": "Cancel a pending challenge",
        "tags": [
          "canonical"
        ]
      }
    },
    "/api/v1/challenges/{challenge_id}/complete": {
      "post": {
        "description": "Verify an offered challenge method and reevaluate the immutable original request into a child authorization.",
        "operationId": "complete_challenge_api_v1_challenges__challenge_id__complete_post",
        "parameters": [
          {
            "description": "Challenge identifier tied to the original pending authorization.",
            "in": "path",
            "name": "challenge_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "example": {
                "method": "sandbox_confirm"
              },
              "schema": {
                "$ref": "#/components/schemas/ChallengeCompleteRequest"
              }
            }
          },
          "description": "For passkey, supply the browser\u2019s assertion for this challenge. sandbox_confirm is simulation only and must be permitted in a sandbox policy.",
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "authorization": "az_child_example",
                  "challenge": "ch_example",
                  "method": "sandbox_confirm",
                  "status": "completed"
                },
                "schema": {
                  "anyOf": [
                    {
                      "$ref": "#/components/schemas/AuthorizeResponse"
                    },
                    {
                      "$ref": "#/components/schemas/ChallengeCompletionReceipt"
                    }
                  ]
                }
              }
            },
            "description": "Scoped browser callers receive ChallengeCompletionReceipt; server callers receive AuthorizeResponse."
          },
          "422": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            },
            "description": "The canonical handler returns a Problem for invalid input; correct the request before retrying."
          }
        },
        "security": [
          {
            "HTTPBearer": []
          }
        ],
        "summary": "Complete explicit action confirmation",
        "tags": [
          "canonical"
        ]
      }
    },
    "/api/v1/challenges/{challenge_id}/passkey/options": {
      "post": {
        "description": "Obtain WebAuthn authentication options bound to this challenge\u2019s immutable request digest.",
        "operationId": "challenge_passkey_options_api_v1_challenges__challenge_id__passkey_options_post",
        "parameters": [
          {
            "description": "Challenge identifier tied to the original pending authorization.",
            "in": "path",
            "name": "challenge_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "type": "object"
                }
              }
            },
            "description": "WebAuthn request options with action-bound challenge bytes, RP id, eligible credentials and required user verification."
          },
          "422": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            },
            "description": "The canonical handler returns a Problem for invalid input; correct the request before retrying."
          }
        },
        "security": [
          {
            "HTTPBearer": []
          }
        ],
        "summary": "Get action-bound passkey options",
        "tags": [
          "canonical"
        ]
      }
    },
    "/api/v1/client-tokens": {
      "post": {
        "description": "Exchange backend authority for a short-lived browser token bound to one subject and exact registered origin.",
        "operationId": "create_client_token_api_v1_client_tokens_post",
        "requestBody": {
          "content": {
            "application/json": {
              "example": {
                "origin": "https://merchant.example",
                "subject": "sub_example",
                "ttl_seconds": 900
              },
              "schema": {
                "$ref": "#/components/schemas/ClientTokenCreate"
              }
            }
          },
          "description": "Resolve subject from your authenticated session. ttl_seconds defaults 900 and permits 60-3600.",
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ClientTokenCreated"
                }
              }
            },
            "description": "New browser token, exact origin, lifetime and Unix-seconds expiry."
          },
          "422": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            },
            "description": "The canonical handler returns a Problem for invalid input; correct the request before retrying."
          }
        },
        "security": [
          {
            "HTTPBearer": []
          }
        ],
        "summary": "Mint a scoped browser token",
        "tags": [
          "canonical"
        ]
      }
    },
    "/api/v1/credential": {
      "get": {
        "description": "Resolve the calling credential\u2019s tenant, environment, authority and proof issuer for trusted backend configuration.",
        "operationId": "credential_identity_api_v1_credential_get",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "credential": "key_example",
                  "environment": "env_example",
                  "environment_kind": "sandbox",
                  "mode": "test",
                  "proof_issuer": "https://app.graypass.org",
                  "scope": "server",
                  "tenant": "tenant_example"
                },
                "schema": {
                  "$ref": "#/components/schemas/CredentialIdentity"
                }
              }
            },
            "description": "Credential id, tenant, environment, key mode, authority and configured proof issuer."
          }
        },
        "security": [
          {
            "HTTPBearer": []
          }
        ],
        "summary": "Read calling credential identity",
        "tags": [
          "canonical"
        ]
      }
    },
    "/api/v1/evaluations": {
      "get": {
        "description": "Read up to 100 evaluation configurations in the authenticated environment.",
        "operationId": "list_evaluations_api_v1_evaluations_get",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": [
                  {
                    "action_keys": [
                      "payout.destination.change"
                    ],
                    "created_at": "2026-10-01T12:00:00Z",
                    "ends_at": "2026-10-31T12:00:00Z",
                    "id": "evl_example",
                    "name": "Payout shadow study",
                    "starts_at": "2026-10-01T12:00:00Z",
                    "status": "open",
                    "success_criteria": {
                      "max_abstention_rate": 0.5,
                      "min_outcome_coverage": 0.5,
                      "min_shadow_decisions": 50
                    }
                  }
                ],
                "schema": {
                  "items": {
                    "$ref": "#/components/schemas/Evaluation"
                  },
                  "type": "array"
                }
              }
            },
            "description": "Array of up to 100 stored evaluation configurations."
          }
        },
        "security": [
          {
            "HTTPBearer": []
          }
        ],
        "summary": "List shadow evaluations",
        "tags": [
          "canonical"
        ]
      },
      "post": {
        "description": "Register the action selection, observation window and thresholds for an operational shadow study.",
        "operationId": "create_evaluation_api_v1_evaluations_post",
        "requestBody": {
          "content": {
            "application/json": {
              "example": {
                "action_keys": [
                  "payout.destination.change"
                ],
                "name": "Payout shadow study",
                "success_criteria": {
                  "max_abstention_rate": 0.5,
                  "min_outcome_coverage": 0.5,
                  "min_shadow_decisions": 50
                }
              },
              "schema": {
                "$ref": "#/components/schemas/EvaluationCreate"
              }
            }
          },
          "description": "Use registered action_keys and optional success_criteria. Defaults are 50 decisions, maximum abstention 0.5 and minimum outcome coverage 0.5; end defaults 30 days after start.",
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "example": {
                  "action_keys": [
                    "payout.destination.change"
                  ],
                  "created_at": "2026-10-01T12:00:00Z",
                  "ends_at": "2026-10-31T12:00:00Z",
                  "id": "evl_example",
                  "name": "Payout shadow study",
                  "starts_at": "2026-10-01T12:00:00Z",
                  "status": "open",
                  "success_criteria": {
                    "max_abstention_rate": 0.5,
                    "min_outcome_coverage": 0.5,
                    "min_shadow_decisions": 50
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/Evaluation"
                }
              }
            },
            "description": "Open evaluation with deduplicated action keys, recorded thresholds and effective observation window."
          },
          "422": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            },
            "description": "The canonical handler returns a Problem for invalid input; correct the request before retrying."
          }
        },
        "security": [
          {
            "HTTPBearer": []
          }
        ],
        "summary": "Create a shadow evaluation",
        "tags": [
          "canonical"
        ]
      }
    },
    "/api/v1/evaluations/{evaluation_id}/close": {
      "post": {
        "description": "Fix the study cutoff and return the resulting criteria report.",
        "operationId": "close_evaluation_api_v1_evaluations__evaluation_id__close_post",
        "parameters": [
          {
            "description": "Evaluation identifier returned when the study was created.",
            "in": "path",
            "name": "evaluation_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EvaluationReport"
                }
              }
            },
            "description": "Closed evaluation report with fixed cutoff and final registered-criterion result."
          },
          "422": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            },
            "description": "The canonical handler returns a Problem for invalid input; correct the request before retrying."
          }
        },
        "security": [
          {
            "HTTPBearer": []
          }
        ],
        "summary": "Close a shadow evaluation",
        "tags": [
          "canonical"
        ]
      }
    },
    "/api/v1/evaluations/{evaluation_id}/report": {
      "get": {
        "description": "Compute the study\u2019s selected shadow-decision metrics and compare them with registered success criteria.",
        "operationId": "evaluation_report_api_v1_evaluations__evaluation_id__report_get",
        "parameters": [
          {
            "description": "Evaluation identifier returned when the study was created.",
            "in": "path",
            "name": "evaluation_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EvaluationReport"
                }
              }
            },
            "description": "Evaluation configuration, aggregated metrics, per-criterion checks and in_progress/passed/failed result."
          },
          "422": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            },
            "description": "The canonical handler returns a Problem for invalid input; correct the request before retrying."
          }
        },
        "security": [
          {
            "HTTPBearer": []
          }
        ],
        "summary": "Read evaluation metrics",
        "tags": [
          "canonical"
        ]
      }
    },
    "/api/v1/meta": {
      "get": {
        "description": "Discover the API version, capability availability and reason-code vocabulary applicable to this service.",
        "operationId": "meta_api_v1_meta_get",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "type": "object"
                }
              }
            },
            "description": "API version, capability declarations and reason-code registry."
          }
        },
        "summary": "Read API capabilities and reason vocabulary",
        "tags": [
          "public"
        ]
      }
    },
    "/api/v1/proofs/{jti}/status": {
      "get": {
        "description": "Look up whether a proof is active, consumed, revoked, expired or unknown in this environment.",
        "operationId": "proof_status_api_v1_proofs__jti__status_get",
        "parameters": [
          {
            "description": "Proof identifier from a trusted authorization trace or verified proof.",
            "in": "path",
            "name": "jti",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "expires_at": "2026-10-01T12:05:00Z",
                  "jti": "proof_example",
                  "revoked_at": null,
                  "status": "consumed"
                },
                "schema": {
                  "$ref": "#/components/schemas/ProofStatus"
                }
              }
            },
            "description": "Proof id and active, consumed, revoked, expired or unknown state."
          },
          "422": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            },
            "description": "The canonical handler returns a Problem for invalid input; correct the request before retrying."
          }
        },
        "security": [
          {
            "HTTPBearer": []
          }
        ],
        "summary": "Read current proof state",
        "tags": [
          "canonical"
        ]
      }
    },
    "/api/v1/sessions": {
      "post": {
        "description": "Start an enroll or observe session for a subject using the scoped browser workflow.",
        "operationId": "create_session_api_v1_sessions_post",
        "requestBody": {
          "content": {
            "application/json": {
              "example": {
                "purpose": "enroll",
                "subject": "sub_example"
              },
              "schema": {
                "$ref": "#/components/schemas/SessionCreate"
              }
            }
          },
          "description": "purpose defaults observe. Optional device_context records application-supplied context. Validate endpoint trust through your application's attestation controls.",
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SessionCreated"
                }
              }
            },
            "description": "Session id, purpose, feature version, scoped signing material and research eligibility flag."
          },
          "422": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            },
            "description": "The canonical handler returns a Problem for invalid input; correct the request before retrying."
          }
        },
        "security": [
          {
            "HTTPBearer": []
          }
        ],
        "summary": "Open an evidence session",
        "tags": [
          "canonical"
        ]
      }
    },
    "/api/v1/sessions/{session_id}/assessment": {
      "get": {
        "description": "Build the current server assessment for the session and its subject.",
        "operationId": "session_assessment_api_v1_sessions__session_id__assessment_get",
        "parameters": [
          {
            "description": "Session identifier owned by the scoped subject in the authenticated environment.",
            "in": "path",
            "name": "session_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "active_seconds": 0.0,
                  "assessed_at": "2026-10-01T12:00:00Z",
                  "claims": [],
                  "coverage": "none",
                  "evidence_windows": 0,
                  "feature_schema_version": "example-feature-version",
                  "freshness_ms": null,
                  "id": "asr_example",
                  "insufficient_evidence": true,
                  "limitations": [
                    "insufficient evidence"
                  ],
                  "modalities_present": [],
                  "model_version": "example-model-version",
                  "rule_version": "example-rule-version",
                  "session": "ses_example",
                  "subject": "sub_example"
                },
                "schema": {
                  "$ref": "#/components/schemas/AssuranceProfile"
                }
              }
            },
            "description": "Server Assurance Profile with claim statuses, evidence freshness and limitations."
          },
          "422": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            },
            "description": "The canonical handler returns a Problem for invalid input; correct the request before retrying."
          }
        },
        "security": [
          {
            "HTTPBearer": []
          }
        ],
        "summary": "Read a server Assurance Profile",
        "tags": [
          "canonical"
        ]
      }
    },
    "/api/v1/sessions/{session_id}/end": {
      "post": {
        "description": "Stop accepting further evidence in the selected session and return its accounting summary.",
        "operationId": "end_session_api_v1_sessions__session_id__end_post",
        "parameters": [
          {
            "description": "Session identifier owned by the scoped subject in the authenticated environment.",
            "in": "path",
            "name": "session_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "duration_seconds": 30,
                  "evidence_windows": 5,
                  "session": "ses_example",
                  "status": "ended"
                },
                "schema": {
                  "$ref": "#/components/schemas/SessionEnded"
                }
              }
            },
            "description": "ended receipt with elapsed session seconds and accounted evidence-window count."
          },
          "422": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            },
            "description": "The canonical handler returns a Problem for invalid input; correct the request before retrying."
          }
        },
        "security": [
          {
            "HTTPBearer": []
          }
        ],
        "summary": "End an evidence session",
        "tags": [
          "canonical"
        ]
      }
    },
    "/api/v1/sessions/{session_id}/evidence": {
      "post": {
        "description": "Submit a session-signed feature window and receive accepted coverage accounting.",
        "operationId": "submit_evidence_api_v1_sessions__session_id__evidence_post",
        "parameters": [
          {
            "description": "Session identifier owned by the scoped subject in the authenticated environment.",
            "in": "path",
            "name": "session_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "example": {
                "duration_ms": 5000,
                "features": {},
                "frame_id": "frame-example-7",
                "purpose": "enroll",
                "research_optin": false,
                "timestamp": 1790856000000,
                "window_end": 1790856000,
                "window_start": 1790855995
              },
              "schema": {
                "$ref": "#/components/schemas/FeatureFrameRequest"
              }
            }
          },
          "description": "Use the browser SDK\u2019s exact-body signing and feature transport. JSON fields alone are insufficient. Match enroll/score purpose to the session; research_optin defaults false.",
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "active_seconds": 0,
                  "coverage": "none",
                  "enrollment_ready": false,
                  "evidence_windows": 0,
                  "modalities_present": [],
                  "reason_codes": [],
                  "status": "neutral"
                },
                "schema": {
                  "$ref": "#/components/schemas/EvidenceAck"
                }
              }
            },
            "description": "accepted, neutral or rejected status plus coverage, reasons and enrollment readiness."
          },
          "422": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            },
            "description": "The canonical handler returns a Problem for invalid input; correct the request before retrying."
          }
        },
        "security": [
          {
            "HTTPBearer": []
          }
        ],
        "summary": "Submit an SDK evidence window",
        "tags": [
          "canonical"
        ]
      }
    },
    "/api/v1/sessions/{session_id}/status": {
      "get": {
        "description": "Inspect accepted evidence coverage, freshness and enrollment readiness without exposing a full server assessment.",
        "operationId": "session_status_api_v1_sessions__session_id__status_get",
        "parameters": [
          {
            "description": "Session identifier owned by the scoped subject in the authenticated environment.",
            "in": "path",
            "name": "session_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "active_seconds": 25,
                  "coverage": "partial",
                  "enrollment_ready": true,
                  "evidence_windows": 5,
                  "freshness_ms": 500,
                  "human_readable": "Evidence is available.",
                  "limitations": [],
                  "modalities_present": [
                    "keyboard"
                  ],
                  "session": "ses_example"
                },
                "schema": {
                  "$ref": "#/components/schemas/StatusSummary"
                }
              }
            },
            "description": "Browser-safe coverage, accepted-window count, active duration, freshness and readiness."
          },
          "422": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            },
            "description": "The canonical handler returns a Problem for invalid input; correct the request before retrying."
          }
        },
        "security": [
          {
            "HTTPBearer": []
          }
        ],
        "summary": "Read browser-safe session status",
        "tags": [
          "canonical"
        ]
      }
    },
    "/api/v1/subjects": {
      "get": {
        "description": "Read a bounded list of non-deleted subjects visible in this environment.",
        "operationId": "list_subjects_api_v1_subjects_get",
        "parameters": [
          {
            "description": "Maximum records requested; default 100. The service bounds it to 1-500. No cursor pagination is exposed.",
            "in": "query",
            "name": "limit",
            "required": false,
            "schema": {
              "default": 100,
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": [
                  {
                    "adaptation_frozen": true,
                    "anchor": "customer_session",
                    "created_at": "2026-10-01T12:00:00Z",
                    "enrollment_state": "not_enrolled",
                    "environment": "env_example",
                    "id": "sub_example",
                    "limitations": [],
                    "recovery_policy": "re_enroll_with_anchor",
                    "revoked_at": null
                  }
                ],
                "schema": {
                  "items": {
                    "$ref": "#/components/schemas/Subject"
                  },
                  "type": "array"
                }
              }
            },
            "description": "Array of visible non-deleted subject records, up to the effective limit."
          },
          "422": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            },
            "description": "The canonical handler returns a Problem for invalid input; correct the request before retrying."
          }
        },
        "security": [
          {
            "HTTPBearer": []
          }
        ],
        "summary": "List subjects",
        "tags": [
          "canonical"
        ]
      },
      "post": {
        "description": "Create the account-to-subject mapping in this environment, or return an existing subject with compatible security settings.",
        "operationId": "create_subject_api_v1_subjects_post",
        "requestBody": {
          "content": {
            "application/json": {
              "example": {
                "anchor": "customer_session",
                "external_ref": "account-42",
                "recovery_policy": "re_enroll_with_anchor"
              },
              "schema": {
                "$ref": "#/components/schemas/SubjectCreate"
              }
            }
          },
          "description": "Supply a stable external_ref. Stronger declared anchors require anchor_evidence_ref; only metadata.label is retained.",
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "example": {
                  "adaptation_frozen": true,
                  "anchor": "customer_session",
                  "created_at": "2026-10-01T12:00:00Z",
                  "enrollment_state": "not_enrolled",
                  "environment": "env_example",
                  "id": "sub_example",
                  "limitations": [],
                  "recovery_policy": "re_enroll_with_anchor",
                  "revoked_at": null
                },
                "schema": {
                  "$ref": "#/components/schemas/Subject"
                }
              }
            },
            "description": "New or existing subject record with enrollment state and recovery settings."
          },
          "422": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            },
            "description": "The canonical handler returns a Problem for invalid input; correct the request before retrying."
          }
        },
        "security": [
          {
            "HTTPBearer": []
          }
        ],
        "summary": "Create a pseudonymous subject",
        "tags": [
          "canonical"
        ]
      }
    },
    "/api/v1/subjects/{subject_id}": {
      "delete": {
        "description": "Delete the subject\u2019s operational assurance data and make its record unavailable to normal subject lookup.",
        "operationId": "delete_subject_api_v1_subjects__subject_id__delete",
        "parameters": [
          {
            "description": "Subject identifier resolved from your authenticated account mapping.",
            "in": "path",
            "name": "subject_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Operational deletion completed; the 204 response has no body."
          },
          "422": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            },
            "description": "The canonical handler returns a Problem for invalid input; correct the request before retrying."
          }
        },
        "security": [
          {
            "HTTPBearer": []
          }
        ],
        "summary": "Delete operational subject data",
        "tags": [
          "canonical"
        ]
      },
      "get": {
        "description": "Retrieve the current subject enrollment and recovery state before starting a lifecycle operation.",
        "operationId": "get_subject_api_v1_subjects__subject_id__get",
        "parameters": [
          {
            "description": "Subject identifier resolved from your authenticated account mapping.",
            "in": "path",
            "name": "subject_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "adaptation_frozen": true,
                  "anchor": "customer_session",
                  "created_at": "2026-10-01T12:00:00Z",
                  "enrollment_state": "not_enrolled",
                  "environment": "env_example",
                  "id": "sub_example",
                  "limitations": [],
                  "recovery_policy": "re_enroll_with_anchor",
                  "revoked_at": null
                },
                "schema": {
                  "$ref": "#/components/schemas/Subject"
                }
              }
            },
            "description": "Current subject state, declared anchor, recovery policy and limitations."
          },
          "422": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            },
            "description": "The canonical handler returns a Problem for invalid input; correct the request before retrying."
          }
        },
        "security": [
          {
            "HTTPBearer": []
          }
        ],
        "summary": "Read a subject",
        "tags": [
          "canonical"
        ]
      }
    },
    "/api/v1/subjects/{subject_id}/adaptation/freeze": {
      "post": {
        "description": "Ensure the subject\u2019s existing template is not silently updated through online adaptation.",
        "operationId": "freeze_adaptation_api_v1_subjects__subject_id__adaptation_freeze_post",
        "parameters": [
          {
            "description": "Subject identifier resolved from your authenticated account mapping.",
            "in": "path",
            "name": "subject_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "adaptation_frozen": true,
                  "anchor": "customer_session",
                  "created_at": "2026-10-01T12:00:00Z",
                  "enrollment_state": "not_enrolled",
                  "environment": "env_example",
                  "id": "sub_example",
                  "limitations": [],
                  "recovery_policy": "re_enroll_with_anchor",
                  "revoked_at": null
                },
                "schema": {
                  "$ref": "#/components/schemas/Subject"
                }
              }
            },
            "description": "Subject record with adaptation_frozen true."
          },
          "422": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            },
            "description": "The canonical handler returns a Problem for invalid input; correct the request before retrying."
          }
        },
        "security": [
          {
            "HTTPBearer": []
          }
        ],
        "summary": "Freeze template adaptation",
        "tags": [
          "canonical"
        ]
      }
    },
    "/api/v1/subjects/{subject_id}/enrollments/complete": {
      "post": {
        "description": "Create a Brainprint enrollment from the subject\u2019s accepted enrollment-session evidence.",
        "operationId": "complete_enrollment_api_v1_subjects__subject_id__enrollments_complete_post",
        "parameters": [
          {
            "description": "Subject identifier resolved from your authenticated account mapping.",
            "in": "path",
            "name": "subject_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "example": {
                "force": false,
                "session": "ses_example"
              },
              "schema": {
                "$ref": "#/components/schemas/EnrollmentComplete"
              }
            }
          },
          "description": "Supply the owned enroll session after its evidence acknowledgement or status reports enrollment_ready=true. The server rechecks readiness at completion; accepted-window count, active seconds and modalities support progress reporting, not client-side thresholds. force defaults false.",
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "anchor": "customer_session",
                  "completed_at": "2026-10-01T12:00:00Z",
                  "created_at": "2026-10-01T12:00:00Z",
                  "id": "enr_example",
                  "limitations": [],
                  "status": "completed",
                  "subject": "sub_example",
                  "windows_accepted": 5
                },
                "schema": {
                  "$ref": "#/components/schemas/Enrollment"
                }
              }
            },
            "description": "Enrollment attempt status, accepted-window count and completion time."
          },
          "422": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            },
            "description": "The canonical handler returns a Problem for invalid input; correct the request before retrying."
          }
        },
        "security": [
          {
            "HTTPBearer": []
          }
        ],
        "summary": "Complete ready enrollment",
        "tags": [
          "canonical"
        ]
      }
    },
    "/api/v1/subjects/{subject_id}/export": {
      "post": {
        "description": "Retrieve a bounded subject-linked export containing lifecycle records and whether a Brainprint exists.",
        "operationId": "export_subject_api_v1_subjects__subject_id__export_post",
        "parameters": [
          {
            "description": "Subject identifier resolved from your authenticated account mapping.",
            "in": "path",
            "name": "subject_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "type": "object"
                }
              }
            },
            "description": "Bounded subject, Brainprint-presence, enrollment, authorization, session, passkey and consent records."
          },
          "422": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            },
            "description": "The canonical handler returns a Problem for invalid input; correct the request before retrying."
          }
        },
        "security": [
          {
            "HTTPBearer": []
          }
        ],
        "summary": "Export bounded subject records",
        "tags": [
          "canonical"
        ]
      }
    },
    "/api/v1/subjects/{subject_id}/passkeys/register/complete": {
      "post": {
        "description": "Verify the WebAuthn registration result and register the resulting credential for the subject.",
        "operationId": "passkey_register_complete_api_v1_subjects__subject_id__passkeys_register_complete_post",
        "parameters": [
          {
            "description": "Subject identifier resolved from your authenticated account mapping.",
            "in": "path",
            "name": "subject_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "example": {
                "credential": {
                  "id": "illustrative-credential-id",
                  "type": "public-key"
                },
                "registration_id": "pkr_example"
              },
              "schema": {
                "additionalProperties": true,
                "type": "object"
              }
            }
          },
          "description": "Send registration_id from options.graypass_registration_id and credential as the browser\u2019s complete serialized PublicKeyCredential attestation response. The example shows the outer container; use the SDK to supply the full WebAuthn fields within it.",
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "created_at": "2026-10-01T12:00:00Z",
                  "id": "pky_example"
                },
                "schema": {
                  "$ref": "#/components/schemas/PasskeyRegistered"
                }
              }
            },
            "description": "Registered passkey id and creation time."
          },
          "422": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            },
            "description": "The canonical handler returns a Problem for invalid input; correct the request before retrying."
          }
        },
        "security": [
          {
            "HTTPBearer": []
          }
        ],
        "summary": "Complete passkey registration",
        "tags": [
          "canonical"
        ]
      }
    },
    "/api/v1/subjects/{subject_id}/passkeys/register/options": {
      "post": {
        "description": "Consume a server-issued registration grant and return WebAuthn creation options for that subject.",
        "operationId": "passkey_register_options_api_v1_subjects__subject_id__passkeys_register_options_post",
        "parameters": [
          {
            "description": "Subject identifier resolved from your authenticated account mapping.",
            "in": "path",
            "name": "subject_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "example": {
                "registration_grant": "illustrative-registration-grant-not-valid"
              },
              "schema": {
                "$ref": "#/components/schemas/PasskeyRegistrationOptionsRequest"
              }
            }
          },
          "description": "Send registration_grant obtained by the authenticated backend. A browser caller must also match subject and origin scope.",
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "type": "object"
                }
              }
            },
            "description": "WebAuthn creation options with graypass_registration_id for the completion call."
          },
          "422": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            },
            "description": "The canonical handler returns a Problem for invalid input; correct the request before retrying."
          }
        },
        "security": [
          {
            "HTTPBearer": []
          }
        ],
        "summary": "Begin passkey registration",
        "tags": [
          "canonical"
        ]
      }
    },
    "/api/v1/subjects/{subject_id}/passkeys/registration-grants": {
      "post": {
        "description": "Authorize one subject-bound passkey registration ceremony from your authenticated backend.",
        "operationId": "create_passkey_registration_grant_api_v1_subjects__subject_id__passkeys_registration_grants_post",
        "parameters": [
          {
            "description": "Subject identifier resolved from your authenticated account mapping.",
            "in": "path",
            "name": "subject_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PasskeyRegistrationGrant"
                }
              }
            },
            "description": "One-time registration token and ISO 8601 expiry."
          },
          "422": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            },
            "description": "The canonical handler returns a Problem for invalid input; correct the request before retrying."
          }
        },
        "security": [
          {
            "HTTPBearer": []
          }
        ],
        "summary": "Issue a passkey registration grant",
        "tags": [
          "canonical"
        ]
      }
    },
    "/api/v1/subjects/{subject_id}/passkeys/{passkey_id}": {
      "delete": {
        "description": "Remove a subject passkey from eligibility for future GrayPass action challenges.",
        "operationId": "revoke_passkey_api_v1_subjects__subject_id__passkeys__passkey_id__delete",
        "parameters": [
          {
            "description": "Subject identifier resolved from your authenticated account mapping.",
            "in": "path",
            "name": "subject_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Identifier of the subject\u2019s registered passkey to revoke.",
            "in": "path",
            "name": "passkey_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Passkey revocation completed; the 204 response has no body."
          },
          "422": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            },
            "description": "The canonical handler returns a Problem for invalid input; correct the request before retrying."
          }
        },
        "security": [
          {
            "HTTPBearer": []
          }
        ],
        "summary": "Revoke a registered passkey",
        "tags": [
          "canonical"
        ]
      }
    },
    "/api/v1/subjects/{subject_id}/recovery": {
      "post": {
        "description": "Move a revoked subject into the permitted re-enrollment path after your application establishes the required anchor.",
        "operationId": "begin_recovery_api_v1_subjects__subject_id__recovery_post",
        "parameters": [
          {
            "description": "Subject identifier resolved from your authenticated account mapping.",
            "in": "path",
            "name": "subject_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "example": {
                "anchor": "customer_session"
              },
              "schema": {
                "$ref": "#/components/schemas/RecoveryBegin"
              }
            }
          },
          "description": "Specify the supported anchor and required anchor_evidence_ref. The subject\u2019s stored recovery policy controls eligibility.",
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "adaptation_frozen": true,
                  "anchor": "customer_session",
                  "created_at": "2026-10-01T12:00:00Z",
                  "enrollment_state": "not_enrolled",
                  "environment": "env_example",
                  "id": "sub_example",
                  "limitations": [],
                  "recovery_policy": "re_enroll_with_anchor",
                  "revoked_at": null
                },
                "schema": {
                  "$ref": "#/components/schemas/Subject"
                }
              }
            },
            "description": "Subject reset to not_enrolled under the accepted replacement anchor."
          },
          "422": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            },
            "description": "The canonical handler returns a Problem for invalid input; correct the request before retrying."
          }
        },
        "security": [
          {
            "HTTPBearer": []
          }
        ],
        "summary": "Begin subject recovery",
        "tags": [
          "canonical"
        ]
      }
    },
    "/api/v1/subjects/{subject_id}/research-consent": {
      "post": {
        "description": "Record a separate, attributed subject decision about behavioral-model research participation.",
        "operationId": "research_consent_api_v1_subjects__subject_id__research_consent_post",
        "parameters": [
          {
            "description": "Subject identifier resolved from your authenticated account mapping.",
            "in": "path",
            "name": "subject_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "example": {
                "consented": false
              },
              "schema": {
                "$ref": "#/components/schemas/ResearchConsentRequest"
              }
            }
          },
          "description": "consented must be a JSON boolean. The API fixes purpose behavioral_model_research and disclosure version research-consent/1.",
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "adaptation_frozen": true,
                  "anchor": "customer_session",
                  "created_at": "2026-10-01T12:00:00Z",
                  "enrollment_state": "not_enrolled",
                  "environment": "env_example",
                  "id": "sub_example",
                  "limitations": [],
                  "recovery_policy": "re_enroll_with_anchor",
                  "revoked_at": null
                },
                "schema": {
                  "$ref": "#/components/schemas/Subject"
                }
              }
            },
            "description": "Current subject record. The consent receipt is stored separately; session research eligibility is reported when creating a session."
          },
          "422": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            },
            "description": "The canonical handler returns a Problem for invalid input; correct the request before retrying."
          }
        },
        "security": [
          {
            "HTTPBearer": []
          }
        ],
        "summary": "Record or withdraw research consent",
        "tags": [
          "canonical"
        ]
      }
    },
    "/api/v1/subjects/{subject_id}/revoke": {
      "post": {
        "description": "Revoke the subject\u2019s existing assurance and terminate its usable session and proof capabilities.",
        "operationId": "revoke_subject_api_v1_subjects__subject_id__revoke_post",
        "parameters": [
          {
            "description": "Subject identifier resolved from your authenticated account mapping.",
            "in": "path",
            "name": "subject_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "adaptation_frozen": true,
                  "anchor": "customer_session",
                  "created_at": "2026-10-01T12:00:00Z",
                  "enrollment_state": "revoked",
                  "environment": "env_example",
                  "id": "sub_example",
                  "limitations": [],
                  "recovery_policy": "re_enroll_with_anchor",
                  "revoked_at": "2026-10-01T12:00:00Z"
                },
                "schema": {
                  "$ref": "#/components/schemas/Subject"
                }
              }
            },
            "description": "Subject record reflecting revoked enrollment state and revocation time."
          },
          "422": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            },
            "description": "The canonical handler returns a Problem for invalid input; correct the request before retrying."
          }
        },
        "security": [
          {
            "HTTPBearer": []
          }
        ],
        "summary": "Revoke subject assurance",
        "tags": [
          "canonical"
        ]
      }
    },
    "/api/v1/verify": {
      "post": {
        "description": "Verify signature/binding/current proof state and optionally consume the proof once for the pending operation.",
        "operationId": "verify_api_v1_verify_post",
        "requestBody": {
          "content": {
            "application/json": {
              "example": {
                "audience": "merchant-api",
                "consume": true,
                "expected_action": "payout.destination.change",
                "expected_action_hash": "0000000000000000000000000000000000000000000000000000000000000000",
                "proof": "not-a-jws"
              },
              "schema": {
                "$ref": "#/components/schemas/VerifyRequest"
              }
            }
          },
          "description": "Supply audience, action and independent action hash from the original request. Perform offline subject/tenant/environment checks first. The example intentionally sends an invalid proof to show refusal.",
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "claims": null,
                  "reason": "malformed",
                  "valid": false
                },
                "schema": {
                  "$ref": "#/components/schemas/VerifyResponse"
                }
              }
            },
            "description": "valid flag with verified claims on success, or refusal reason on failure; both can use HTTP 200."
          },
          "422": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            },
            "description": "The canonical handler returns a Problem for invalid input; correct the request before retrying."
          }
        },
        "security": [
          {
            "HTTPBearer": []
          }
        ],
        "summary": "Verify and optionally consume a proof",
        "tags": [
          "canonical"
        ]
      }
    }
  }
}
