Schemas

Request and response schemas with field meanings and constraints. Required fields must be present. Nullable fields explicitly permit null. Defaults apply when a field is omitted. Unknown request fields are rejected where additionalProperties: false is specified. Keep response parsers tolerant of additive fields within the same contract version.

ActionCreate

Field / type	Required	Meaning and constraints
`key` string	Yes	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_])*$"`
`name` string	Yes	Customer-visible display name for the action or evaluation. minLength: `1` maxLength: `120`
`consequence` string	Yes	Plain-language consequence if the wrong person performs the protected action. minLength: `1` maxLength: `500`
`risk_class` string	No	Customer-selected consequence category for the action: low, elevated, high or critical. enum: `["low", "elevated", "high", "critical"]` default: `"high"`
`resource_type` string	No	Customer-defined category of the protected resource, such as merchant. default: `"resource"` maxLength: `64`
`context_schema` object	No	JSON Schema object applied to authorization context. Include every business value that must be bound to approval. additionalProperties: `true`
`allowed_audiences` Array of string	Yes	Relying-party audience identifiers allowed to receive proofs for this action. minItems: `1`
`allowed_callers` Array of string	No	Credential identifiers allowed to authorize this action. An empty list permits any eligible server credential in the same environment.
`proof_ttl_seconds` integer	No	Proof lifetime in seconds, measured from issuance; the accepted range is 30-900 seconds. default: `300` minimum: `30.0` maximum: `900.0`

additionalProperties: false

ActionUpdate

Change action display metadata or evaluation mode; policy security settings are versioned separately.

Field / type	Required	Meaning and constraints
`name` string (maxLength: `120`) or null	No	Customer-visible display name for the action or evaluation.
`consequence` string (maxLength: `500`) or null	No	Plain-language consequence if the wrong person performs the protected action.
`mode` string (enum: `["test", "shadow", "enforce"]`) or null	No	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.

additionalProperties: false

Actor

Actor bound to the protected business request.

Field / type	Required	Meaning and constraints
`id` string	Yes	Application actor identifier. Use the subject identifier for the supported human proof-verification path. minLength: `1` maxLength: `256`
`type` string	No	Actor category; only human is supported in this API version. const: `"human"` default: `"human"`

additionalProperties: false

AssuranceClaim

A named evidence claim with categorical status, coverage, freshness, and assessment context.

Field / type	Required	Meaning and constraints
`claim` string	Yes	Claim name, such as operator_continuity or human_presence. Capability availability is separately reported by metadata.
`status` `ClaimStatus`	Yes	Status of this named claim. Use unsupported and insufficient_evidence to select the configured evidence-collection or approval path.
`coverage` string	Yes	Evidence-coverage category: none, sparse, partial or sufficient. Describes the amount and variety of accepted evidence. enum: `["none", "sparse", "partial", "sufficient"]`
`freshness_ms` integer (minimum: `0.0`) or null	No	Age of the relevant evidence in milliseconds; null when freshness cannot be established.
`evidence_refs` Array of string	No	Opaque references to the evidence supporting this claim.
`reason_codes` Array of string	No	Stable reason identifiers explaining acceptance, limitations or a decision; resolve them in the reason-code catalog.
`limitations` Array of string	No	Applicable limitations that must accompany interpretation of the result.

additionalProperties: false

AssuranceProfile

Server assessment of available evidence for one subject and session. It contains no calibrated confidence score.

Field / type	Required	Meaning and constraints
`id` string	Yes	Identifier of this record. Treat it as opaque and retain it for subsequent operations.
`subject` string	Yes	Pseudonymous subject identifier in the authenticated tenant and environment.
`session` string or null	No	Observation or enrollment session identifier, as required by the operation.
`assessed_at` string	Yes	Assessment time as an ISO 8601 timestamp.
`claims` Array of `AssuranceClaim`	Yes	Individual assurance claims with their own status and limitations.
`coverage` string	Yes	Evidence-coverage category: none, sparse, partial or sufficient. Describes the amount and variety of accepted evidence. enum: `["none", "sparse", "partial", "sufficient"]`
`evidence_windows` integer	No	Number of accepted, non-overlapping evidence windows accounted for in this session or profile. default: `0`
`active_seconds` number	No	Duration of accepted active evidence in seconds. default: `0.0`
`modalities_present` Array of string	No	Names of observed evidence modalities included in coverage accounting.
`freshness_ms` integer or null	No	Age of the relevant evidence in milliseconds; null when freshness cannot be established.
`limitations` Array of string	No	Applicable limitations that must accompany interpretation of the result.
`model_version` string	Yes	Version identifier for the model used in this assessment. Retain it when comparing assessment results.
`rule_version` string	Yes	Version identifier for the assurance rules used in this assessment.
`feature_schema_version` string	Yes	Version identifier for the feature representation used by the session or assessment.
`insufficient_evidence` boolean	Yes	True when evidence is insufficient for the assessment’s supported claims.

additionalProperties: false

AuthorizationTrace

Server-readable record of the original request binding, decision and subsequent challenge, proof, review and outcome state.

Field / type	Required	Meaning and constraints
`id` string	Yes	Identifier of this record. Treat it as opaque and retain it for subsequent operations.
`action` string	Yes	Registered action key, such as payout.destination.change.
`subject` string	Yes	Pseudonymous subject identifier in the authenticated tenant and environment.
`actor` string	Yes	Bound human actor identifier.
`actor_type` string	Yes	Bound actor category; only human is supported. const: `"human"`
`resource_type` string	Yes	Customer-defined category of the protected resource, such as merchant.
`resource_digest` string	Yes	One-way digest of the resource binding.
`context_digest` string	Yes	Digest of the context binding. Render your independently retained business details for user confirmation.
`action_hash` string	Yes	SHA-256 digest binding the canonical authorization material. Compare it with the hash computed from the original server-held request.
`audience` string	Yes	Expected relying-party audience. It must be permitted by the action and independently known to the verifier.
`mode` string	Yes	Action evaluation mode. Test and shadow return decisions without enforceable proofs. An eligible enforce-mode allow can carry a proof. enum: `["test", "shadow", "enforce"]`
`policy_version` integer or null	No	Immutable policy version number evaluated for this decision.
`decision` string	Yes	Policy result: allow, challenge, hold or deny. Inspect mode and proof requirements before performing any business mutation. enum: `["allow", "challenge", "hold", "deny"]`
`reason_codes` Array of string	Yes	Stable reason identifiers explaining acceptance, limitations or a decision; resolve them in the reason-code catalog.
`assurance` `AssuranceProfile`	Yes	Assurance Profile used for this authorization decision.
`challenge` `ChallengeTrace` or null	No	Challenge associated with the request. Null means no challenge is included in this response.
`proof_id` string or null	No	Proof identifier (jti), or null when no proof was issued.
`proof` `ProofTrace` or null	No	Nested proof state. Its compact field carries the signed proof; AuthorizeResponse.proof carries the compact string directly.
`parent` string or null	No	Parent authorization identifier for a challenge or review child; null for an original request.
`review_status` string or null	No	Recorded manual-review state, or null when no review occurred.
`review_authorization_id` string or null	No	Child authorization produced by an approved review, or null.
`reviewed_at` string or null	No	Manual-review time as an ISO 8601 timestamp, or null.
`reviewed_by` string or null	No	Identifier of the credential attributed to the manual review, or null.
`outcome` string or null	No	Business outcome reported by the customer application, with supporting evidence maintained by the customer.
`outcome_reported_at` string or null	No	Recorded business-outcome time as an ISO 8601 timestamp, or null.
`requested_at` string	Yes	Recorded request time as an ISO 8601 timestamp in the trace, distinct from the caller’s Unix-seconds input.
`decided_at` string	Yes	Decision time as an ISO 8601 timestamp.
`latency_ms` integer	Yes	Server-recorded decision latency in milliseconds.

AuthorizeRequest

Immutable business-request material supplied by the relying-party backend after its own authentication and permission checks.

Field / type	Required	Meaning and constraints
`subject` string	Yes	Pseudonymous subject identifier in the authenticated tenant and environment.
`actor` `Actor` or null	No	Optional explicit human actor. When omitted, the subject is the actor. Use that same subject identifier for the supported human proof-verification path.
`action` string	Yes	Registered action key, such as payout.destination.change. maxLength: `128`
`resource` `Resource`	Yes	Resource type and identifier for the exact object being changed.
`context` object	No	Business values bound to the decision and validated against the active context schema. Use safe integers rather than floating-point values. additionalProperties: `true`
`audience` string	Yes	Expected relying-party audience. It must be permitted by the action and independently known to the verifier. minLength: `1` maxLength: `128`
`requested_at` integer	Yes	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`
`nonce` string	Yes	Fresh unpredictable nonce for this request. Retain it with the pending operation and reuse it only for retries of that same request. minLength: `16` maxLength: `128`
`idempotency_key` string	Yes	Stable application request identifier reused only for identical retries; changed material with the same key conflicts. minLength: `8` maxLength: `128`
`session` string or null	No	Optional observation session for this subject. When omitted, the service selects the subject’s latest applicable session.
`mandate_ref` string or null	No	Supported value: null. Omit the field or send null.

additionalProperties: false

AuthorizeResponse

Immediate policy result. Only an enforce-mode allow can include a compact Proof of Agency.

Field / type	Required	Meaning and constraints
`id` string	Yes	Identifier of this record. Treat it as opaque and retain it for subsequent operations.
`decision` string	Yes	Policy result: allow, challenge, hold or deny. Inspect mode and proof requirements before performing any business mutation. enum: `["allow", "challenge", "hold", "deny"]`
`mode` string	Yes	Action evaluation mode. Test and shadow return decisions without enforceable proofs. An eligible enforce-mode allow can carry a proof. enum: `["test", "shadow", "enforce"]`
`action` string	Yes	Registered action key, such as payout.destination.change.
`action_hash` string	Yes	SHA-256 digest binding the canonical authorization material. Compare it with the hash computed from the original server-held request.
`environment` string	Yes	Environment identifier that scopes this record; sandbox and live resources are separate.
`policy_version` integer	Yes	Immutable policy version number evaluated for this decision.
`reason_codes` Array of string	Yes	Stable reason identifiers explaining acceptance, limitations or a decision; resolve them in the reason-code catalog.
`human_readable` `HumanReadable`	Yes	Display status and detail explaining the result. Branch on the stable decision and reason-code fields.
`assurance` `AssuranceProfile`	Yes	Assurance Profile used for the decision.
`challenge` `ChallengeDescriptor` or null	No	Challenge associated with the request. Null means no challenge is included in this response.
`proof` string or null	No	Compact signed JWS, or null. Require enforce-mode allow, trusted binding checks and successful online consumption before execution.
`proof_id` string or null	No	Proof identifier (jti), or null when no proof was issued.
`trace_id` string	Yes	Identifier to retain for authorization trace lookup and operational diagnosis.
`decided_at` string	Yes	Decision time as an ISO 8601 timestamp.
`latency_ms` integer	Yes	Server-recorded decision latency in milliseconds.

ChallengeCancelled

Acknowledgment that the selected challenge was cancelled.

Field / type	Required	Meaning and constraints
`id` string	Yes	Identifier of this record. Treat it as opaque and retain it for subsequent operations.
`status` string	Yes	Lifecycle state of this record; use the operation-specific values listed in the schema. const: `"cancelled"`

ChallengeCompleteRequest

Complete an action-bound challenge using one of its permitted methods.

Field / type	Required	Meaning and constraints
`method` string	Yes	Chosen challenge method; use only a method offered by this challenge. enum: `["passkey", "sandbox_confirm"]`
`assertion` object (additionalProperties: `true`) or null	No	WebAuthn authentication assertion produced for this challenge’s options when method is passkey. Omit for sandbox_confirm.

additionalProperties: false

ChallengeCompletionReceipt

Browser-safe completion receipt. The backend must retrieve and validate the referenced child authorization.

Field / type	Required	Meaning and constraints
`challenge` string	Yes	Completed challenge identifier.
`status` string	Yes	Lifecycle state of this record; use the operation-specific values listed in the schema. const: `"completed"`
`authorization` string	Yes	Authorization identifier associated with this receipt. Resolve it on the backend and verify the bound proof before execution.
`method` string	Yes	Chosen challenge method; use only a method offered by this challenge. enum: `["passkey", "sandbox_confirm"]`

ChallengeDescriptor

Challenge offered by an authorization decision, including methods and expiry.

Field / type	Required	Meaning and constraints
`id` string	Yes	Identifier of this record. Treat it as opaque and retain it for subsequent operations.
`methods` Array of string	Yes	Permitted challenge methods. sandbox_confirm is a simulated ceremony restricted to the sandbox.
`expires_at` string	Yes	Expiry time as an ISO 8601 timestamp. Use the capability before this time; obtain a fresh one afterward.

ChallengeDisplay

Display information for explicit action confirmation. Digests complement the relying party’s independently retained business details.

Field / type	Required	Meaning and constraints
`action_key` string	Yes	Stable registered key for the action being approved.
`action` string	Yes	Customer-visible protected-action name.
`consequence` string	Yes	Plain-language consequence if the wrong person performs the protected action.
`resource_type` string	Yes	Customer-defined category of the protected resource, such as merchant.
`resource_digest` string	Yes	One-way digest of the resource binding.
`context_digest` string	Yes	Digest of the context binding. Render your independently retained business details for user confirmation.
`audience` string	Yes	Expected relying-party audience. It must be permitted by the action and independently known to the verifier.
`requesting_application` string	Yes	Relying-party application identified in the challenge display.

ChallengePublicView

Browser-safe view of a scoped challenge and the action it asks the subject to approve.

Field / type	Required	Meaning and constraints
`id` string	Yes	Identifier of this record. Treat it as opaque and retain it for subsequent operations.
`status` string	Yes	Lifecycle state of this record; use the operation-specific values listed in the schema.
`methods` Array of string	Yes	Permitted challenge methods. sandbox_confirm is a simulated ceremony restricted to the sandbox.
`expires_at` string	Yes	Expiry time as an ISO 8601 timestamp. Use the capability before this time; obtain a fresh one afterward.
`display` `ChallengeDisplay`	Yes	Action display metadata and digests bound to the original request.

ChallengeTrace

Challenge lifecycle state embedded in an authorization trace.

Field / type	Required	Meaning and constraints
`id` string	Yes	Identifier of this record. Treat it as opaque and retain it for subsequent operations.
`status` string	Yes	Lifecycle state of this record; use the operation-specific values listed in the schema.
`method_used` string or null	No	Method used to complete the challenge, or null before completion.
`strength` string or null	No	Recorded challenge assurance label. Distinguishes action-bound passkey confirmation from sandbox simulation.
`expires_at` string	Yes	Expiry time as an ISO 8601 timestamp. Use the capability before this time; obtain a fresh one afterward.
`completed_at` string or null	No	Completion time as an ISO 8601 timestamp, or null before completion.

ClaimStatus

Permitted statuses for a named assurance claim. Read the status with the claim definition, coverage, freshness, and assessment context.

string

enum: ["confirmed", "likely", "uncertain", "not_confirmed", "detected", "not_detected", "not_present", "insufficient_evidence", "unsupported"]

ClientTokenCreate

Mint a short-lived, subject-bound browser credential for a registered origin.

Field / type	Required	Meaning and constraints
`subject` string	Yes	Pseudonymous subject identifier in the authenticated tenant and environment.
`origin` string	Yes	Exact browser origin including scheme, hostname and non-default port. It must be registered for the tenant. minLength: `1` maxLength: `2048`
`ttl_seconds` integer	No	Browser-token lifetime in seconds; default 900, permitted range 60-3600. default: `900` minimum: `60.0` maximum: `3600.0`

additionalProperties: false

ClientTokenCreated

Browser credential issuance result. Treat client_token as a secret capability.

Field / type	Required	Meaning and constraints
`client_token` string	Yes	Short-lived bearer token for the selected subject and origin. Keep it out of URLs, logs and persistent browser storage.
`expires_at` number	Yes	Token expiry as Unix time in seconds, which differs from the ISO timestamps used by most resource records.
`ttl_seconds` integer	Yes	Browser-token lifetime in seconds; default 900, permitted range 60-3600.
`origin` string	Yes	Exact browser origin including scheme, hostname and non-default port. It must be registered for the tenant.

CredentialIdentity

Non-secret identity and scope of the authenticated server credential, used to establish trusted verification expectations.

Field / type	Required	Meaning and constraints
`credential` string	Yes	Public identifier of the calling credential.
`tenant` string	Yes	Tenant identifier to bind proof verification to the intended customer.
`environment` string	Yes	Environment identifier that scopes this record; sandbox and live resources are separate.
`environment_kind` string	Yes	Environment category: sandbox or live. enum: `["sandbox", "live"]`
`scope` string	Yes	Credential authority category. Canonical backend routes require server or admin; client scope is insufficient. enum: `["client", "server", "admin"]`
`mode` string	Yes	Credential key mode, test or live; distinct from an action’s test, shadow or enforce mode. enum: `["test", "live"]`
`proof_issuer` string	Yes	Expected proof issuer reported by the trusted configured service; never learn an issuer from an unverified proof.

Enrollment

Enrollment attempt and completion state for a subject’s behavioral reference.

Field / type	Required	Meaning and constraints
`id` string	Yes	Identifier of this record. Treat it as opaque and retain it for subsequent operations.
`subject` string	Yes	Pseudonymous subject identifier in the authenticated tenant and environment.
`status` string	Yes	Lifecycle state of this record; use the operation-specific values listed in the schema. enum: `["pending", "completed", "failed"]`
`anchor` string	Yes	Account anchor established by the customer identity process and recorded by GrayPass.
`windows_accepted` integer	Yes	Count of accepted evidence windows recorded for this enrollment.
`created_at` string	Yes	Creation time as an ISO 8601 timestamp.
`completed_at` string or null	No	Completion time as an ISO 8601 timestamp, or null before completion.
`limitations` Array of string	No	Applicable limitations that must accompany interpretation of the result.

EnrollmentComplete

Ask the server to complete a subject’s enrollment from its ready enrollment session.

Field / type	Required	Meaning and constraints
`session` string	Yes	Enrollment-purpose session owned by the subject in the path.
`force` boolean	No	Whether to replace an existing template after accepted-window, duration and modality readiness checks pass. default: `false`

additionalProperties: false

Evaluation

Stored selection, thresholds and observation window for a shadow integration study.

Field / type	Required	Meaning and constraints
`id` string	Yes	Identifier of this record. Treat it as opaque and retain it for subsequent operations.
`name` string	Yes	Customer-visible display name for the action or evaluation.
`action_keys` Array of string	Yes	Registered action keys included in the evaluation; the service deduplicates this selection.
`success_criteria` `EvaluationCriteria`	Yes	Recorded thresholds for shadow-decision count, abstention rate and outcome coverage, evaluated against the selected traces.
`status` string	Yes	Lifecycle state of this record; use the operation-specific values listed in the schema. enum: `["open", "closed"]`
`starts_at` string	Yes	Timezone-aware ISO 8601 study start. If omitted during creation, the service uses the current time.
`ends_at` string or null	No	Timezone-aware ISO 8601 study end, later than starts_at. Creation defaults to 30 days after the start; closing can shorten this cutoff.
`created_at` string	Yes	Creation time as an ISO 8601 timestamp.

EvaluationCreate

Create a shadow integration study for registered actions with explicit success criteria.

Field / type	Required	Meaning and constraints
`name` string	Yes	Customer-visible display name for the action or evaluation. maxLength: `120`
`action_keys` Array of string	Yes	Registered action keys included in the evaluation; the service deduplicates this selection. minItems: `1` maxItems: `100`
`success_criteria` `EvaluationCriteria`	No	Recorded thresholds for shadow-decision count, abstention rate and outcome coverage, evaluated against the selected traces.
`starts_at` string or null	No	Timezone-aware ISO 8601 study start. If omitted during creation, the service uses the current time.
`ends_at` string or null	No	Timezone-aware ISO 8601 study end, later than starts_at. Creation defaults to 30 days after the start; closing can shorten this cutoff.

additionalProperties: false

EvaluationCriteria

Thresholds for operational integration metrics used to evaluate the selected shadow decisions.

Field / type	Required	Meaning and constraints
`min_shadow_decisions` integer	No	Minimum number of selected shadow decisions; default 50. default: `50` minimum: `1.0` maximum: `1000000.0`
`max_abstention_rate` number	No	Maximum permitted fraction of selected decisions carrying decision.insufficient_evidence, from 0 to 1; default 0.5. default: `0.5` minimum: `0.0` maximum: `1.0`
`min_outcome_coverage` number	No	Minimum fraction of selected decisions with recorded customer outcomes, from 0 to 1; default 0.5. default: `0.5` minimum: `0.0` maximum: `1.0`

additionalProperties: false

EvaluationMetrics

Aggregated trace and customer-outcome metrics within the study window. Missing denominators can produce null ratios.

Field / type	Required	Meaning and constraints
`decisions` integer	Yes	Number of selected shadow authorization decisions.
`by_decision` object	Yes	Counts by decision label. additionalProperties: integer
`by_mode` object	Yes	Counts by action evaluation mode in the selected records. additionalProperties: integer
`abstention_rate` number or null	No	Fraction of selected decisions carrying decision.insufficient_evidence, or null when the selection is empty.
`experimental_operator_change_indicators` integer	Yes	Number of selected decisions carrying the operator_change.detected indicator. Interpret with the sample and customer-reviewed outcomes.
`challenges` integer	Yes	Count of selected decisions that requested a challenge.
`false_challenge_proxy` number or null	No	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.
`coverage_distribution` object	Yes	Counts by assurance coverage category. additionalProperties: integer
`outcomes` object	Yes	Counts by customer-reported outcome label. additionalProperties: integer
`outcome_coverage` number	Yes	Fraction of selected decisions with an outcome, from 0 to 1.
`decision_latency_ms` object	Yes	Server decision latency summaries in milliseconds; entries may be null when no samples exist. additionalProperties: integer or null
`note` string	Yes	Interpretation limitations supplied with these operational metrics.

EvaluationReport

Evaluation configuration, current metrics and registered-criterion results.

Field / type	Required	Meaning and constraints
`id` string	Yes	Identifier of this record. Treat it as opaque and retain it for subsequent operations.
`name` string	Yes	Customer-visible display name for the action or evaluation.
`action_keys` Array of string	Yes	Registered action keys included in the evaluation; the service deduplicates this selection.
`success_criteria` `EvaluationCriteria`	Yes	Recorded thresholds for shadow-decision count, abstention rate and outcome coverage, evaluated against the selected traces.
`status` string	Yes	Lifecycle state of this record; use the operation-specific values listed in the schema. enum: `["open", "closed"]`
`starts_at` string	Yes	Timezone-aware ISO 8601 study start. If omitted during creation, the service uses the current time.
`ends_at` string or null	No	Timezone-aware ISO 8601 study end, later than starts_at. Creation defaults to 30 days after the start; closing can shorten this cutoff.
`created_at` string	Yes	Creation time as an ISO 8601 timestamp.
`metrics` `EvaluationMetrics`	Yes	Operational metrics computed from selected retained traces.
`checks` object	Yes	Per-criterion pass/fail results against the recorded thresholds. additionalProperties: boolean
`result` string	Yes	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"]`

EvidenceAck

Receipt for one evidence window, including whether it contributed to accepted coverage.

Field / type	Required	Meaning and constraints
`status` string	Yes	accepted contributes to coverage. Interpret neutral and rejected through the associated reason codes. enum: `["accepted", "neutral", "rejected"]`
`reason_codes` Array of string	No	Stable reason identifiers explaining acceptance, limitations or a decision; resolve them in the reason-code catalog.
`coverage` string	Yes	Evidence-coverage category: none, sparse, partial or sufficient. Describes the amount and variety of accepted evidence. enum: `["none", "sparse", "partial", "sufficient"]`
`evidence_windows` integer	Yes	Number of accepted, non-overlapping evidence windows accounted for in this session or profile.
`active_seconds` number	Yes	Duration of accepted active evidence in seconds.
`modalities_present` Array of string	No	Names of observed evidence modalities included in coverage accounting.
`enrollment_ready` boolean	No	Whether the server’s accepted coverage meets enrollment readiness. Client elapsed time alone is insufficient. default: `false`

FeatureFrameRequest

A feature window submitted by the supported SDK, which handles extraction, session signing and transport.

Field / type	Required	Meaning and constraints
`frame_id` string	Yes	Unique identifier for this frame within the session; repeated identifiers are refused by replay controls. minLength: `1` maxLength: `128`
`timestamp` number	Yes	Frame timestamp. The browser SDK emits Unix milliseconds; native-compatible Unix seconds are also normalized. Use the SDK’s clock convention consistently.
`duration_ms` number	Yes	Frame duration in milliseconds; finite values from 0 through 600000 are accepted by the schema. Accepted coverage applies additional server checks. minimum: `0.0` maximum: `600000.0`
`window_start` number (minimum: `0.0`) or null	No	Optional evidence-window start as Unix seconds. When omitted, bounds are derived from timestamp and duration_ms.
`window_end` number (minimum: `0.0`) or null	No	Optional evidence-window end as Unix seconds. Bounds must describe a fresh, non-overlapping window for this session.
`features` object	Yes	SDK-produced modality feature object containing bounded derived features. Raw key content, images, video and audio stay outside the evidence submission. additionalProperties: `true`
`purpose` string	No	Frame purpose: enroll for enrollment evidence; score for observation. It must match the session’s purpose. default: `"score"` pattern: `"^(score\|enroll)$"`
`research_optin` boolean	No	Separate per-frame JSON opt-in, default false. Retention requires this field plus current subject consent, environment participation and deployment eligibility. default: `false`

HumanReadable

Customer-display wording explaining a decision; stable reason codes carry the programmatic meaning.

Field / type	Required	Meaning and constraints
`status` string	Yes	Short display label for the decision; use reason codes for stable programmatic behavior.
`detail` string	Yes	Human-readable explanation. Use stable codes and typed decision fields for application branching.

ManualReviewRequest

Record an attributed resolution for a held authorization.

Field / type	Required	Meaning and constraints
`resolution` string	Yes	Attributed manual review result: approve or reject. Approval still requires a fresh verified child decision. enum: `["approve", "reject"]`
`note` string (maxLength: `500`) or null	No	Optional review note; retained as a digest rather than a free-text business record. Keep your review evidence in your own authorized system.

additionalProperties: false

OutcomeReceipt

Acknowledgment of the customer’s recorded business-outcome label.

Field / type	Required	Meaning and constraints
`authorization` string	Yes	Authorization identifier associated with this receipt. Resolve it on the backend and verify the bound proof before execution.
`outcome` string	Yes	Business outcome reported by the customer application, with supporting evidence maintained by the customer.
`reported_at` string	Yes	Time the outcome was recorded, as an ISO 8601 timestamp.

OutcomeReport

Report what the customer application actually did after a decision; reporting never executes or authorizes the action.

Field / type	Required	Meaning and constraints
`outcome` string	Yes	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"]`
`note` string (maxLength: `500`) or null	No	Optional outcome note stored as a one-way digest. Keep a readable case narrative in your own application.

additionalProperties: false

PasskeyRegistered

Identifier and creation time of the registered subject passkey.

Field / type	Required	Meaning and constraints
`id` string	Yes	Identifier of this record. Treat it as opaque and retain it for subsequent operations.
`created_at` string	Yes	Creation time as an ISO 8601 timestamp.

PasskeyRegistrationGrant

Single-use backend grant permitting the intended subject to begin passkey registration.

Field / type	Required	Meaning and constraints
`token` string	Yes	Short-lived, one-time passkey-registration grant. Deliver only to the authenticated subject’s intended browser and keep out of logs.
`expires_at` string	Yes	Expiry time as an ISO 8601 timestamp. Use the capability before this time; obtain a fresh one afterward.

PasskeyRegistrationOptionsRequest

Exchange a subject-bound one-time grant for WebAuthn registration options.

Field / type	Required	Meaning and constraints
`registration_grant` string	Yes	One-time server-issued grant scoped to this subject’s passkey registration. minLength: `32` maxLength: `256`

additionalProperties: false

PolicyRequirements

Requirements and refusal precedence applied by one immutable policy version.

Field / type	Required	Meaning and constraints
`claims` object	No	Minimum status by claim name. The default requests operator_continuity at uncertain. Choose a requirement supported by the named claim. additionalProperties: string
`coverage_min` string	No	Minimum accepted evidence coverage category; default partial. enum: `["none", "sparse", "partial", "sufficient"]` default: `"partial"`
`freshness_max_ms` integer	No	Maximum acceptable evidence age in milliseconds; default 60000 (one minute). default: `60000` minimum: `1000.0` maximum: `3600000.0`
`insufficient_evidence` string	No	Decision used for insufficient evidence: challenge, hold or deny. Default challenge. enum: `["challenge", "hold", "deny"]` default: `"challenge"`
`challenge_methods` Array of string	No	Permitted compensating methods; default passkey. sandbox_confirm is sandbox-only simulation.
`explicit_approval_required` boolean	No	Whether action-bound explicit approval is required even if other evidence satisfies policy. default: `false`
`challenge_compensates` Array of string	No	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.
`max_challenges` integer	No	Maximum challenges in one request chain before escalation to hold; default 2. default: `2` minimum: `1.0` maximum: `5.0`
`hold_on` Array of string	No	Reason codes that force hold under this policy. Default empty list.
`deny_on` Array of string	No	Reason codes that force deny under this policy. Default empty list.

additionalProperties: false

PolicyVersion

Immutable decision contract and its draft, active or retired lifecycle state.

Field / type	Required	Meaning and constraints
`id` string	Yes	Identifier of this record. Treat it as opaque and retain it for subsequent operations.
`action` string	Yes	Identifier of the protected-action record owning this version.
`version` integer	Yes	Monotonically assigned policy version number for the action.
`status` string	Yes	Lifecycle state of this record; use the operation-specific values listed in the schema. enum: `["draft", "active", "retired"]`
`requirements` `PolicyRequirements`	Yes	Assurance, freshness and challenge requirements evaluated by this policy version.
`context_schema` object	Yes	JSON Schema object applied to authorization context. Include every business value that must be bound to approval. additionalProperties: `true`
`allowed_audiences` Array of string	Yes	Relying-party audience identifiers allowed to receive proofs for this action.
`allowed_callers` Array of string	Yes	Credential identifiers allowed to authorize this action. An empty list permits any eligible server credential in the same environment.
`proof_ttl_seconds` integer	Yes	Proof lifetime in seconds, measured from issuance; the accepted range is 30-900 seconds.
`content_hash` string	Yes	Digest of the immutable policy content; retain it when comparing policy configurations.
`created_at` string	Yes	Creation time as an ISO 8601 timestamp.
`activated_at` string or null	No	Policy activation time as an ISO 8601 timestamp, or null for a draft.
`retired_at` string or null	No	Policy retirement time as an ISO 8601 timestamp, or null when not retired.

PolicyVersionCreate

Create a draft policy. Omitted optional security settings inherit from the active version; activation is a separate operation.

Field / type	Required	Meaning and constraints
`requirements` `PolicyRequirements`	Yes	Required complete requirement set for the new version; omitted fields inside it use the documented requirement defaults.
`context_schema` object (additionalProperties: `true`) or null	No	JSON Schema object applied to authorization context. Include every business value that must be bound to approval.
`allowed_audiences` Array of string (minItems: `1`) or null	No	Relying-party audience identifiers allowed to receive proofs for this action.
`allowed_callers` Array of string or null	No	Credential identifiers allowed to authorize this action. An empty list permits any eligible server credential in the same environment.
`proof_ttl_seconds` integer (minimum: `30.0` maximum: `900.0`) or null	No	Proof lifetime in seconds, measured from issuance; the accepted range is 30-900 seconds.

additionalProperties: false

Problem

Canonical problem-details response. Inspect status and code; detail and title are explanatory text.

Field / type	Required	Meaning and constraints
`type` string	No	Problem type URI; about:blank for the standard problem envelope. default: `"about:blank"`
`title` string	Yes	Short human-readable error summary.
`status` integer	Yes	HTTP status code represented as an integer.
`detail` string or null	No	Optional explanatory detail; wording is not a stable programmatic contract. default: `null`
`code` string	Yes	Stable canonical error identifier used for integration behavior.
`instance` string or null	No	Optional identifier for this particular problem occurrence. default: `null`

ProofStatus

Current scoped server state for a proof identifier. Use proof verification and consumption before execution.

Field / type	Required	Meaning and constraints
`jti` string	Yes	Proof identifier from a verified proof or trusted authorization trace.
`status` string	Yes	active, consumed, revoked, expired or unknown. Only active is eligible for attempted consumption. enum: `["active", "consumed", "revoked", "expired", "unknown"]`
`expires_at` string or null	No	Expiry time as an ISO 8601 timestamp. Use the capability before this time; obtain a fresh one afterward.
`revoked_at` string or null	No	Revocation time as an ISO 8601 timestamp, or null when not revoked.

ProofTrace

Signed proof and current state associated with an authorization trace.

Field / type	Required	Meaning and constraints
`id` string	Yes	Identifier of this record. Treat it as opaque and retain it for subsequent operations.
`compact` string or null	No	Compact JWS when available; keep it out of logs and browser-controlled execution decisions.
`status` string	Yes	Lifecycle state of this record; use the operation-specific values listed in the schema.
`expires_at` string or null	No	Expiry time as an ISO 8601 timestamp. Use the capability before this time; obtain a fresh one afterward.

ProtectedAction

Protected-action metadata together with the currently selected policy settings and evaluation mode.

Field / type	Required	Meaning and constraints
`id` string	Yes	Identifier of this record. Treat it as opaque and retain it for subsequent operations.
`environment` string	Yes	Environment identifier that scopes this record; sandbox and live resources are separate.
`key` string	Yes	Stable dotted action key used by authorization, such as payout.destination.change.
`name` string	Yes	Customer-visible display name for the action or evaluation.
`consequence` string	Yes	Plain-language consequence if the wrong person performs the protected action.
`risk_class` string	Yes	Customer-selected consequence category for the action: low, elevated, high or critical. enum: `["low", "elevated", "high", "critical"]`
`resource_type` string	Yes	Customer-defined category of the protected resource, such as merchant.
`context_schema` object	Yes	JSON Schema object applied to authorization context. Include every business value that must be bound to approval. additionalProperties: `true`
`mode` string	Yes	Action evaluation mode. Test and shadow return decisions without enforceable proofs. An eligible enforce-mode allow can carry a proof. enum: `["test", "shadow", "enforce"]`
`allowed_audiences` Array of string	Yes	Relying-party audience identifiers allowed to receive proofs for this action.
`allowed_callers` Array of string	Yes	Credential identifiers allowed to authorize this action. An empty list permits any eligible server credential in the same environment.
`proof_ttl_seconds` integer	Yes	Proof lifetime in seconds, measured from issuance; the accepted range is 30-900 seconds.
`active_policy_version` integer or null	No	Currently active policy version number, or null when no version is active.
`created_at` string	Yes	Creation time as an ISO 8601 timestamp.
`updated_at` string	Yes	Most recent update time as an ISO 8601 timestamp.

RecoveryBegin

Start re-enrollment for a revoked subject under its configured recovery policy.

Field / type	Required	Meaning and constraints
`anchor` string	Yes	Account anchor established by the customer identity process and recorded by GrayPass. enum: `["none", "customer_session", "idp", "passkey", "verified_identity"]`
`anchor_evidence_ref` string (minLength: `8` maxLength: `256`) or null	No	Reference to the customer’s 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.

additionalProperties: false

ResearchConsentRequest

Record or revoke subject research consent separately from ordinary service use and subject creation.

Field / type	Required	Meaning and constraints
`consented` boolean	Yes	Strict JSON boolean: true records consent and false records withdrawal. The server fixes the receipt purpose and disclosure version. Deployment eligibility is configured separately.

additionalProperties: false

Resource

Exact business resource bound to an authorization.

Field / type	Required	Meaning and constraints
`type` string	Yes	Application resource category, such as merchant. minLength: `1` maxLength: `64`
`id` string	Yes	Application resource identifier, derived from the authenticated pending business request. minLength: `1` maxLength: `256`

additionalProperties: false

ReviewApprovedReceipt

Approved review receipt with a newly evaluated child decision. Inspect that decision and complete its required verification before execution.

Field / type	Required	Meaning and constraints
`authorization` string	Yes	Authorization identifier associated with this receipt. Resolve it on the backend and verify the bound proof before execution.
`resolution` string	Yes	Attributed manual review result: approve or reject. Approval still requires a fresh verified child decision. const: `"approve"`
`decision` `AuthorizeResponse`	Yes	Fresh child authorization response, requiring the usual parent, request binding and proof checks.

ReviewRejectedReceipt

Rejected manual-review receipt and its recorded rejection outcome.

Field / type	Required	Meaning and constraints
`authorization` string	Yes	Authorization identifier associated with this receipt. Resolve it on the backend and verify the bound proof before execution.
`resolution` string	Yes	Attributed manual review result: approve or reject. Approval still requires a fresh verified child decision. const: `"reject"`
`outcome` `OutcomeReceipt`	Yes	Outcome receipt for the manual rejection.

SessionCreate

Open an enrollment or observation session for the authenticated subject.

Field / type	Required	Meaning and constraints
`subject` string	Yes	Pseudonymous subject identifier in the authenticated tenant and environment.
`purpose` string	No	enroll collects enrollment evidence; observe assesses continuity. The default is observe. enum: `["observe", "enroll"]` default: `"observe"`
`device_context` object (additionalProperties: `true`) or null	No	Optional customer-provided device context, without independent device integrity attestation. Apply your endpoint controls to establish device trust.

additionalProperties: false

SessionCreated

Session identifier, feature contract and short-lived evidence-signing material returned to its scoped caller.

Field / type	Required	Meaning and constraints
`id` string	Yes	Identifier of this record. Treat it as opaque and retain it for subsequent operations.
`subject` string	Yes	Pseudonymous subject identifier in the authenticated tenant and environment.
`purpose` string	Yes	Session purpose, enroll or observe.
`feature_schema_version` string	Yes	Version identifier for the feature representation used by the session or assessment.
`frame_signing_key` string or null	No	Session-specific signing secret for SDK evidence transport, when issued. Never log or expose it to another subject.
`frame_signing_alg` string or null	No	Algorithm identifier for the session’s evidence-signing material.
`research_enabled` boolean	No	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. default: `false`
`created_at` string	Yes	Creation time as an ISO 8601 timestamp.

SessionEnded

Receipt for an ended evidence session and its accounted duration and windows.

Field / type	Required	Meaning and constraints
`session` string	Yes	Observation or enrollment session identifier, as required by the operation.
`status` string	Yes	Lifecycle state of this record; use the operation-specific values listed in the schema. const: `"ended"`
`duration_seconds` number	Yes	Elapsed session duration in seconds, distinct from accepted active evidence duration. minimum: `0.0`
`evidence_windows` integer	Yes	Number of accepted, non-overlapping evidence windows accounted for in this session or profile. minimum: `0.0`

StatusSummary

Browser-safe coverage and enrollment-readiness summary without a score or full server assessment.

Field / type	Required	Meaning and constraints
`session` string	Yes	Observation or enrollment session identifier, as required by the operation.
`coverage` string	Yes	Evidence-coverage category: none, sparse, partial or sufficient. Describes the amount and variety of accepted evidence. enum: `["none", "sparse", "partial", "sufficient"]`
`evidence_windows` integer	Yes	Number of accepted, non-overlapping evidence windows accounted for in this session or profile.
`active_seconds` number	Yes	Duration of accepted active evidence in seconds.
`modalities_present` Array of string	No	Names of observed evidence modalities included in coverage accounting.
`freshness_ms` integer or null	Yes	Age of the relevant evidence in milliseconds; null when freshness cannot be established.
`human_readable` string	Yes	Human-readable coverage/readiness explanation for the user interface.
`enrollment_ready` boolean	No	Whether the server’s accepted coverage meets enrollment readiness. Client elapsed time alone is insufficient. default: `false`
`limitations` Array of string	No	Applicable limitations that must accompany interpretation of the result.

Subject

Pseudonymous subject lifecycle record within one environment.

Field / type	Required	Meaning and constraints
`id` string	Yes	Identifier of this record. Treat it as opaque and retain it for subsequent operations.
`environment` string	Yes	Environment identifier that scopes this record; sandbox and live resources are separate.
`enrollment_state` string	Yes	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"]`
`anchor` string	Yes	Account anchor established by the customer identity process and recorded by GrayPass.
`recovery_policy` string	Yes	Recovery rule governing whether re-enrollment requires an anchor or a separate manual-review process.
`adaptation_frozen` boolean	Yes	Whether online template adaptation is frozen; true prevents silent template adaptation.
`created_at` string	Yes	Creation time as an ISO 8601 timestamp.
`revoked_at` string or null	No	Revocation time as an ISO 8601 timestamp, or null when not revoked.
`limitations` Array of string	No	Applicable limitations that must accompany interpretation of the result.

SubjectCreate

Create or retrieve the subject mapped to a stable customer reference and compatible security settings.

Field / type	Required	Meaning and constraints
`external_ref` string	Yes	Stable customer account reference, 1-256 characters. It is received by the API and retained as a keyed hash; avoid using direct personal information. minLength: `1` maxLength: `256`
`anchor` string	No	Account anchor established by the customer identity process and recorded by GrayPass. enum: `["none", "customer_session", "idp", "passkey", "verified_identity"]` default: `"customer_session"`
`anchor_evidence_ref` string (minLength: `8` maxLength: `256`) or null	No	Reference to the customer’s 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.
`recovery_policy` string	No	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"]` default: `"re_enroll_with_anchor"`
`metadata` object	No	Optional customer metadata object. This version retains only the label key; avoid sensitive information. additionalProperties: `true`

additionalProperties: false

VerifyRequest

Online verification against expected action binding, with optional atomic one-time consumption.

Field / type	Required	Meaning and constraints
`proof` string	Yes	Compact JWS obtained through your trusted authorization workflow. First perform the documented offline and subject/tenant/environment binding checks.
`audience` string	Yes	Expected relying-party audience. It must be permitted by the action and independently known to the verifier.
`expected_action` string	Yes	Action key independently retained with the pending business request.
`expected_action_hash` string	Yes	64-character SHA-256 hex action hash computed from the original server-held material, never learned from an unverified proof. minLength: `64` maxLength: `64`
`consume` boolean	No	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. default: `false`

additionalProperties: false

VerifyResponse

Verification result. HTTP 200 can still mean valid is false; never authorize based on transport status alone.

Field / type	Required	Meaning and constraints
`valid` boolean	Yes	True only when all online checks succeed and, if requested, one-time consumption succeeds.
`reason` string or null	No	Stable verification refusal reason when invalid, otherwise null.
`claims` object (additionalProperties: `true`) or null	No	Verified proof claims when valid, otherwise null. Compare them with the application’s independent expectations.