Reference
Schemas
The wire format, generated from the application's models. Unknown fields are rejected on requests; responses may gain fields within a contract version.
Actions and policies
ProtectedAction
{
"properties": {
"id": {
"type": "string",
"title": "Id"
},
"environment": {
"type": "string",
"title": "Environment"
},
"key": {
"type": "string",
"title": "Key"
},
"name": {
"type": "string",
"title": "Name"
},
"consequence": {
"type": "string",
"title": "Consequence"
},
"risk_class": {
"type": "string",
"enum": [
"low",
"elevated",
"high",
"critical"
],
"title": "Risk Class"
},
"resource_type": {
"type": "string",
"title": "Resource Type"
},
"context_schema": {
"additionalProperties": true,
"type": "object",
"title": "Context Schema"
},
"mode": {
"type": "string",
"enum": [
"test",
"shadow",
"enforce"
],
"title": "Mode"
},
"allowed_audiences": {
"items": {
"type": "string"
},
"type": "array",
"title": "Allowed Audiences"
},
"allowed_callers": {
"items": {
"type": "string"
},
"type": "array",
"title": "Allowed Callers"
},
"proof_ttl_seconds": {
"type": "integer",
"title": "Proof Ttl Seconds"
},
"active_policy_version": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Active Policy Version"
},
"created_at": {
"type": "string",
"title": "Created At"
},
"updated_at": {
"type": "string",
"title": "Updated At"
}
},
"type": "object",
"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"
}ActionCreate
{
"properties": {
"key": {
"type": "string",
"maxLength": 128,
"pattern": "^[a-z][a-z0-9_]*(\\.[a-z][a-z0-9_]*)*$",
"title": "Key",
"description": "Stable dotted key, e.g. payout.destination.change"
},
"name": {
"type": "string",
"maxLength": 120,
"minLength": 1,
"title": "Name"
},
"consequence": {
"type": "string",
"maxLength": 500,
"minLength": 1,
"title": "Consequence",
"description": "Plain-language statement of what happens if the wrong person performs this action."
},
"risk_class": {
"type": "string",
"enum": [
"low",
"elevated",
"high",
"critical"
],
"title": "Risk Class",
"default": "high"
},
"resource_type": {
"type": "string",
"maxLength": 64,
"title": "Resource Type",
"default": "resource"
},
"context_schema": {
"additionalProperties": true,
"type": "object",
"title": "Context Schema",
"description": "JSON Schema (object) for the context field."
},
"allowed_audiences": {
"items": {
"type": "string"
},
"type": "array",
"minItems": 1,
"title": "Allowed Audiences",
"description": "Relying-party audiences permitted to receive proofs."
},
"allowed_callers": {
"items": {
"type": "string"
},
"type": "array",
"title": "Allowed Callers",
"description": "Credential ids permitted to authorize. Empty permits any server credential in this environment."
},
"proof_ttl_seconds": {
"type": "integer",
"maximum": 900.0,
"minimum": 30.0,
"title": "Proof Ttl Seconds",
"default": 300
}
},
"additionalProperties": false,
"type": "object",
"required": [
"key",
"name",
"consequence",
"allowed_audiences"
],
"title": "ActionCreate"
}PolicyRequirements
{
"properties": {
"claims": {
"additionalProperties": {
"type": "string"
},
"type": "object",
"title": "Claims",
"description": "Minimum status per claim."
},
"coverage_min": {
"type": "string",
"enum": [
"none",
"sparse",
"partial",
"sufficient"
],
"title": "Coverage Min",
"default": "partial"
},
"freshness_max_ms": {
"type": "integer",
"maximum": 3600000.0,
"minimum": 1000.0,
"title": "Freshness Max Ms",
"default": 60000
},
"insufficient_evidence": {
"type": "string",
"enum": [
"challenge",
"hold",
"deny"
],
"title": "Insufficient Evidence",
"default": "challenge"
},
"challenge_methods": {
"items": {
"type": "string",
"enum": [
"passkey",
"sandbox_confirm"
]
},
"type": "array",
"title": "Challenge Methods"
},
"explicit_approval_required": {
"type": "boolean",
"title": "Explicit Approval Required",
"default": false
},
"challenge_compensates": {
"items": {
"type": "string",
"enum": [
"operator_continuity",
"human_presence",
"coverage",
"freshness"
]
},
"type": "array",
"title": "Challenge Compensates"
},
"max_challenges": {
"type": "integer",
"maximum": 5.0,
"minimum": 1.0,
"title": "Max Challenges",
"default": 2
},
"hold_on": {
"items": {
"type": "string"
},
"type": "array",
"title": "Hold On",
"description": "Reason codes that force hold."
},
"deny_on": {
"items": {
"type": "string"
},
"type": "array",
"title": "Deny On",
"description": "Reason codes that force deny."
}
},
"additionalProperties": false,
"type": "object",
"title": "PolicyRequirements",
"description": "Requirements a policy version places on the Assurance Profile."
}PolicyVersion
{
"properties": {
"id": {
"type": "string",
"title": "Id"
},
"action": {
"type": "string",
"title": "Action"
},
"version": {
"type": "integer",
"title": "Version"
},
"status": {
"type": "string",
"enum": [
"draft",
"active",
"retired"
],
"title": "Status"
},
"requirements": {
"$ref": "#/components/schemas/PolicyRequirements"
},
"context_schema": {
"additionalProperties": true,
"type": "object",
"title": "Context Schema"
},
"allowed_audiences": {
"items": {
"type": "string"
},
"type": "array",
"title": "Allowed Audiences"
},
"allowed_callers": {
"items": {
"type": "string"
},
"type": "array",
"title": "Allowed Callers"
},
"proof_ttl_seconds": {
"type": "integer",
"title": "Proof Ttl Seconds"
},
"content_hash": {
"type": "string",
"title": "Content Hash"
},
"created_at": {
"type": "string",
"title": "Created At"
},
"activated_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Activated At"
},
"retired_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Retired At"
}
},
"type": "object",
"required": [
"id",
"action",
"version",
"status",
"requirements",
"context_schema",
"allowed_audiences",
"allowed_callers",
"proof_ttl_seconds",
"content_hash",
"created_at"
],
"title": "PolicyVersion"
}PolicyVersionCreate
{
"properties": {
"requirements": {
"$ref": "#/components/schemas/PolicyRequirements"
},
"context_schema": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"title": "Context Schema"
},
"allowed_audiences": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array",
"minItems": 1
},
{
"type": "null"
}
],
"title": "Allowed Audiences"
},
"allowed_callers": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Allowed Callers"
},
"proof_ttl_seconds": {
"anyOf": [
{
"type": "integer",
"maximum": 900.0,
"minimum": 30.0
},
{
"type": "null"
}
],
"title": "Proof Ttl Seconds"
}
},
"additionalProperties": false,
"type": "object",
"required": [
"requirements"
],
"title": "PolicyVersionCreate",
"description": "One immutable decision contract.\n\nSecurity-relevant action fields live in the version, not in mutable action\nmetadata. Omitted fields are copied from the currently active version."
}Subjects, sessions, and evidence
Subject
{
"properties": {
"id": {
"type": "string",
"title": "Id"
},
"environment": {
"type": "string",
"title": "Environment"
},
"enrollment_state": {
"type": "string",
"enum": [
"not_enrolled",
"enrolling",
"enrolled",
"revoked",
"deleted"
],
"title": "Enrollment State"
},
"anchor": {
"type": "string",
"title": "Anchor"
},
"recovery_policy": {
"type": "string",
"title": "Recovery Policy"
},
"adaptation_frozen": {
"type": "boolean",
"title": "Adaptation Frozen"
},
"created_at": {
"type": "string",
"title": "Created At"
},
"revoked_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Revoked At"
},
"limitations": {
"items": {
"type": "string"
},
"type": "array",
"title": "Limitations"
}
},
"type": "object",
"required": [
"id",
"environment",
"enrollment_state",
"anchor",
"recovery_policy",
"adaptation_frozen",
"created_at"
],
"title": "Subject"
}SubjectCreate
{
"properties": {
"external_ref": {
"type": "string",
"maxLength": 256,
"minLength": 1,
"title": "External Ref",
"description": "Your identifier for the person; stored only as a keyed hash."
},
"anchor": {
"type": "string",
"enum": [
"none",
"customer_session",
"idp",
"passkey",
"verified_identity"
],
"title": "Anchor",
"default": "customer_session"
},
"anchor_evidence_ref": {
"anyOf": [
{
"type": "string",
"maxLength": 256,
"minLength": 8
},
{
"type": "null"
}
],
"title": "Anchor Evidence Ref"
},
"recovery_policy": {
"type": "string",
"enum": [
"re_enroll_with_anchor",
"re_enroll_any",
"manual_review"
],
"title": "Recovery Policy",
"default": "re_enroll_with_anchor"
},
"metadata": {
"additionalProperties": true,
"type": "object",
"title": "Metadata"
}
},
"additionalProperties": false,
"type": "object",
"required": [
"external_ref"
],
"title": "SubjectCreate"
}ClientTokenCreate
{
"properties": {
"subject": {
"type": "string",
"title": "Subject"
},
"origin": {
"type": "string",
"maxLength": 2048,
"minLength": 1,
"title": "Origin"
},
"ttl_seconds": {
"type": "integer",
"maximum": 3600.0,
"minimum": 60.0,
"title": "Ttl Seconds",
"default": 900
}
},
"additionalProperties": false,
"type": "object",
"required": [
"subject",
"origin"
],
"title": "ClientTokenCreate"
}ClientTokenCreated
{
"properties": {
"client_token": {
"type": "string",
"title": "Client Token"
},
"expires_at": {
"type": "number",
"title": "Expires At"
},
"ttl_seconds": {
"type": "integer",
"title": "Ttl Seconds"
},
"origin": {
"type": "string",
"title": "Origin"
}
},
"type": "object",
"required": [
"client_token",
"expires_at",
"ttl_seconds",
"origin"
],
"title": "ClientTokenCreated"
}SessionCreate
{
"properties": {
"subject": {
"type": "string",
"title": "Subject"
},
"purpose": {
"type": "string",
"enum": [
"observe",
"enroll"
],
"title": "Purpose",
"default": "observe"
},
"device_context": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"title": "Device Context"
}
},
"additionalProperties": false,
"type": "object",
"required": [
"subject"
],
"title": "SessionCreate"
}SessionCreated
{
"properties": {
"id": {
"type": "string",
"title": "Id"
},
"subject": {
"type": "string",
"title": "Subject"
},
"purpose": {
"type": "string",
"title": "Purpose"
},
"feature_schema_version": {
"type": "string",
"title": "Feature Schema Version"
},
"frame_signing_key": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Frame Signing Key"
},
"frame_signing_alg": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Frame Signing Alg"
},
"research_enabled": {
"type": "boolean",
"title": "Research Enabled",
"default": false
},
"created_at": {
"type": "string",
"title": "Created At"
}
},
"type": "object",
"required": [
"id",
"subject",
"purpose",
"feature_schema_version",
"created_at"
],
"title": "SessionCreated"
}EvidenceAck
{
"properties": {
"status": {
"type": "string",
"enum": [
"accepted",
"neutral",
"rejected"
],
"title": "Status"
},
"reason_codes": {
"items": {
"type": "string"
},
"type": "array",
"title": "Reason Codes"
},
"coverage": {
"type": "string",
"enum": [
"none",
"sparse",
"partial",
"sufficient"
],
"title": "Coverage"
},
"evidence_windows": {
"type": "integer",
"title": "Evidence Windows"
},
"active_seconds": {
"type": "number",
"title": "Active Seconds"
},
"modalities_present": {
"items": {
"type": "string"
},
"type": "array",
"title": "Modalities Present"
},
"enrollment_ready": {
"type": "boolean",
"title": "Enrollment Ready",
"default": false
}
},
"type": "object",
"required": [
"status",
"coverage",
"evidence_windows",
"active_seconds"
],
"title": "EvidenceAck"
}StatusSummary
{
"properties": {
"session": {
"type": "string",
"title": "Session"
},
"coverage": {
"type": "string",
"enum": [
"none",
"sparse",
"partial",
"sufficient"
],
"title": "Coverage"
},
"evidence_windows": {
"type": "integer",
"title": "Evidence Windows"
},
"active_seconds": {
"type": "number",
"title": "Active Seconds"
},
"modalities_present": {
"items": {
"type": "string"
},
"type": "array",
"title": "Modalities Present"
},
"freshness_ms": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Freshness Ms"
},
"human_readable": {
"type": "string",
"title": "Human Readable"
},
"enrollment_ready": {
"type": "boolean",
"title": "Enrollment Ready",
"default": false
},
"limitations": {
"items": {
"type": "string"
},
"type": "array",
"title": "Limitations"
}
},
"type": "object",
"required": [
"session",
"coverage",
"evidence_windows",
"active_seconds",
"freshness_ms",
"human_readable"
],
"title": "StatusSummary",
"description": "What a browser credential may learn: a human-readable state, never a score."
}Enrollment
{
"properties": {
"id": {
"type": "string",
"title": "Id"
},
"subject": {
"type": "string",
"title": "Subject"
},
"status": {
"type": "string",
"enum": [
"pending",
"completed",
"failed"
],
"title": "Status"
},
"anchor": {
"type": "string",
"title": "Anchor"
},
"windows_accepted": {
"type": "integer",
"title": "Windows Accepted"
},
"created_at": {
"type": "string",
"title": "Created At"
},
"completed_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Completed At"
},
"limitations": {
"items": {
"type": "string"
},
"type": "array",
"title": "Limitations"
}
},
"type": "object",
"required": [
"id",
"subject",
"status",
"anchor",
"windows_accepted",
"created_at"
],
"title": "Enrollment"
}EnrollmentComplete
{
"properties": {
"session": {
"type": "string",
"title": "Session"
},
"force": {
"type": "boolean",
"title": "Force",
"default": false
}
},
"additionalProperties": false,
"type": "object",
"required": [
"session"
],
"title": "EnrollmentComplete"
}Authorization
AuthorizeRequest
{
"properties": {
"subject": {
"type": "string",
"title": "Subject"
},
"actor": {
"anyOf": [
{
"$ref": "#/components/schemas/Actor"
},
{
"type": "null"
}
]
},
"action": {
"type": "string",
"maxLength": 128,
"title": "Action"
},
"resource": {
"$ref": "#/components/schemas/Resource"
},
"context": {
"additionalProperties": true,
"type": "object",
"title": "Context"
},
"audience": {
"type": "string",
"maxLength": 128,
"minLength": 1,
"title": "Audience"
},
"requested_at": {
"type": "integer",
"minimum": 0.0,
"title": "Requested At",
"description": "Unix time when the relying party created this request."
},
"nonce": {
"type": "string",
"maxLength": 128,
"minLength": 16,
"title": "Nonce"
},
"idempotency_key": {
"type": "string",
"maxLength": 128,
"minLength": 8,
"title": "Idempotency Key"
},
"session": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Session",
"description": "Pin a specific observation session; defaults to the subject's latest."
},
"mandate_ref": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Mandate Ref",
"description": "Unsupported: agent mandates are not available and this must be null."
}
},
"additionalProperties": false,
"type": "object",
"required": [
"subject",
"action",
"resource",
"audience",
"requested_at",
"nonce",
"idempotency_key"
],
"title": "AuthorizeRequest"
}AuthorizeResponse
{
"properties": {
"id": {
"type": "string",
"title": "Id"
},
"decision": {
"type": "string",
"enum": [
"allow",
"challenge",
"hold",
"deny"
],
"title": "Decision"
},
"mode": {
"type": "string",
"enum": [
"test",
"shadow",
"enforce"
],
"title": "Mode"
},
"action": {
"type": "string",
"title": "Action"
},
"action_hash": {
"type": "string",
"title": "Action Hash"
},
"environment": {
"type": "string",
"title": "Environment"
},
"policy_version": {
"type": "integer",
"title": "Policy Version"
},
"reason_codes": {
"items": {
"type": "string"
},
"type": "array",
"title": "Reason Codes"
},
"human_readable": {
"$ref": "#/components/schemas/HumanReadable"
},
"assurance": {
"$ref": "#/components/schemas/AssuranceProfile"
},
"challenge": {
"anyOf": [
{
"$ref": "#/components/schemas/ChallengeDescriptor"
},
{
"type": "null"
}
]
},
"proof": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Proof",
"description": "Compact JWS Proof of Agency; only for allow in enforce mode."
},
"proof_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Proof Id"
},
"trace_id": {
"type": "string",
"title": "Trace Id"
},
"decided_at": {
"type": "string",
"title": "Decided At"
},
"latency_ms": {
"type": "integer",
"title": "Latency Ms"
}
},
"type": "object",
"required": [
"id",
"decision",
"mode",
"action",
"action_hash",
"environment",
"policy_version",
"reason_codes",
"human_readable",
"assurance",
"trace_id",
"decided_at",
"latency_ms"
],
"title": "AuthorizeResponse"
}AssuranceProfile
{
"properties": {
"id": {
"type": "string",
"title": "Id"
},
"subject": {
"type": "string",
"title": "Subject"
},
"session": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Session"
},
"assessed_at": {
"type": "string",
"title": "Assessed At"
},
"claims": {
"items": {
"$ref": "#/components/schemas/AssuranceClaim"
},
"type": "array",
"title": "Claims"
},
"coverage": {
"type": "string",
"enum": [
"none",
"sparse",
"partial",
"sufficient"
],
"title": "Coverage"
},
"evidence_windows": {
"type": "integer",
"title": "Evidence Windows",
"default": 0
},
"active_seconds": {
"type": "number",
"title": "Active Seconds",
"default": 0.0
},
"modalities_present": {
"items": {
"type": "string"
},
"type": "array",
"title": "Modalities Present"
},
"freshness_ms": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Freshness Ms"
},
"limitations": {
"items": {
"type": "string"
},
"type": "array",
"title": "Limitations"
},
"model_version": {
"type": "string",
"title": "Model Version"
},
"rule_version": {
"type": "string",
"title": "Rule Version"
},
"feature_schema_version": {
"type": "string",
"title": "Feature Schema Version"
},
"insufficient_evidence": {
"type": "boolean",
"title": "Insufficient Evidence"
}
},
"additionalProperties": false,
"type": "object",
"required": [
"id",
"subject",
"assessed_at",
"claims",
"coverage",
"model_version",
"rule_version",
"feature_schema_version",
"insufficient_evidence"
],
"title": "AssuranceProfile"
}AssuranceClaim
{
"properties": {
"claim": {
"type": "string",
"title": "Claim"
},
"status": {
"$ref": "#/components/schemas/ClaimStatus"
},
"coverage": {
"type": "string",
"enum": [
"none",
"sparse",
"partial",
"sufficient"
],
"title": "Coverage"
},
"freshness_ms": {
"anyOf": [
{
"type": "integer",
"minimum": 0.0
},
{
"type": "null"
}
],
"title": "Freshness Ms"
},
"evidence_refs": {
"items": {
"type": "string"
},
"type": "array",
"title": "Evidence Refs"
},
"reason_codes": {
"items": {
"type": "string"
},
"type": "array",
"title": "Reason Codes"
},
"limitations": {
"items": {
"type": "string"
},
"type": "array",
"title": "Limitations"
}
},
"additionalProperties": false,
"type": "object",
"required": [
"claim",
"status",
"coverage"
],
"title": "AssuranceClaim"
}ChallengeCompleteRequest
{
"properties": {
"method": {
"type": "string",
"enum": [
"passkey",
"sandbox_confirm"
],
"title": "Method"
},
"assertion": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"title": "Assertion",
"description": "WebAuthn assertion (passkey)."
}
},
"additionalProperties": false,
"type": "object",
"required": [
"method"
],
"title": "ChallengeCompleteRequest"
}OutcomeReport
{
"properties": {
"outcome": {
"type": "string",
"enum": [
"executed",
"not_executed",
"manually_approved",
"manually_rejected",
"confirmed_attack",
"false_challenge",
"customer_override",
"unknown"
],
"title": "Outcome"
},
"note": {
"anyOf": [
{
"type": "string",
"maxLength": 500
},
{
"type": "null"
}
],
"title": "Note",
"description": "Stored only as a digest."
}
},
"additionalProperties": false,
"type": "object",
"required": [
"outcome"
],
"title": "OutcomeReport"
}Proofs
VerifyRequest
{
"properties": {
"proof": {
"type": "string",
"title": "Proof"
},
"audience": {
"type": "string",
"title": "Audience"
},
"expected_action": {
"type": "string",
"title": "Expected Action"
},
"expected_action_hash": {
"type": "string",
"maxLength": 64,
"minLength": 64,
"title": "Expected Action Hash"
},
"consume": {
"type": "boolean",
"title": "Consume",
"description": "One-time consumption at GrayPass in addition to offline checks.",
"default": false
}
},
"additionalProperties": false,
"type": "object",
"required": [
"proof",
"audience",
"expected_action",
"expected_action_hash"
],
"title": "VerifyRequest"
}VerifyResponse
{
"properties": {
"valid": {
"type": "boolean",
"title": "Valid"
},
"reason": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Reason"
},
"claims": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"title": "Claims"
}
},
"type": "object",
"required": [
"valid"
],
"title": "VerifyResponse"
}ProofStatus
{
"properties": {
"jti": {
"type": "string",
"title": "Jti"
},
"status": {
"type": "string",
"enum": [
"active",
"consumed",
"revoked",
"expired",
"unknown"
],
"title": "Status"
},
"expires_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Expires At"
},
"revoked_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Revoked At"
}
},
"type": "object",
"required": [
"jti",
"status"
],
"title": "ProofStatus"
}Generated from the API contract in contracts/ and the source in docs/. The build fails if this page disagrees with the running API.