Skip to content
API Reference
API Reference
Zones

Policy Sets

List policy sets in a zone
zones.policy_sets.list(strzone_id, PolicySetListParams**kwargs) -> PolicySetListResponse
GET/zones/{zone_id}/policy-sets
Create a new policy set
zones.policy_sets.create(strzone_id, PolicySetCreateParams**kwargs) -> PolicySetWithBinding
POST/zones/{zone_id}/policy-sets
Get a policy set by ID
zones.policy_sets.retrieve(strpolicy_set_id, PolicySetRetrieveParams**kwargs) -> PolicySetWithBinding
GET/zones/{zone_id}/policy-sets/{policy_set_id}
Update a policy set
zones.policy_sets.update(strpolicy_set_id, PolicySetUpdateParams**kwargs) -> PolicySetWithBinding
PATCH/zones/{zone_id}/policy-sets/{policy_set_id}
Archive a policy set
zones.policy_sets.archive(strpolicy_set_id, PolicySetArchiveParams**kwargs) -> PolicySetWithBinding
DELETE/zones/{zone_id}/policy-sets/{policy_set_id}
ModelsExpand Collapse
class Attestation: …

JWS Flattened JSON Serialization (RFC 7515 §7.2.2) of a policy set attestation. The protected header carries the signing algorithm and key identifier; the payload is a base64url-encoded AttestationStatement canonicalized per RFC 8785 (JCS). Verify using the zone JWKS endpoint (RFC 7517). Currently signed with RS256; future zone key types (e.g. EdDSA) will be indicated by the "alg" header — no envelope changes required.

payload: str

Base64url-encoded AttestationStatement (RFC 7515 §3). Decode to inspect attestation content. The RFC 8785 canonical form of the decoded JSON is the JWS Signing Input alongside the protected header.

protected: str

Base64url-encoded JWS protected header (RFC 7515 §4). Contains at minimum "alg" (signing algorithm — currently RS256, will migrate to EdDSA) and "kid" (signing key identifier resolvable via the zone JWKS endpoint).

signature: str

Base64url-encoded digital signature computed over the JWS Signing Input (ASCII(protected) || '.' || payload) per RFC 7515 §5.1.

class AttestationStatement: …

Decoded content of an Attestation JWS payload. Describes the exact policy set version composition at attestation time. This schema defines what consumers see after base64url-decoding the Attestation.payload field.

attested_at: datetime
formatdate-time
attested_by: str
key_id: str

Key ID of the signing key used to produce the attestation signature. Matches the "kid" in the JWS protected header.

manifest_sha: str

SHA-256 of the policy set version manifest. Verifiers MUST check this matches the policy_set_version.manifest_sha to detect attestation/version mismatches.

policy_set_id: str
policy_set_version: int
status: Literal["created", "re_signed"]

Event that produced this attestation. "created" is the initial attestation at version creation; "re_signed" is a re-attestation after key rotation (same content, new signature).

Accepts one of the following:
"created"
"re_signed"
type: Literal["policy_set_attestation"]

Statement type discriminator

v: Literal[1]

Statement schema version

zone_id: str
class PolicySet: …
id: str
created_at: datetime
formatdate-time
created_by: str
name: str
owner_type: Literal["platform", "customer"]

Who manages this policy set:

  • "platform" — managed by the Keycard platform (system policies).
  • "customer" — managed by the tenant (custom policies).
Accepts one of the following:
"platform"
"customer"
scope_type: Literal["zone", "resource", "user", "session"]

The scope at which this policy set applies:

  • "zone" — applies to all requests in the zone.
  • "resource" — scoped to a specific resource.
  • "user" — scoped to a specific user.
  • "session" — scoped to a specific session.
Accepts one of the following:
"zone"
"resource"
"user"
"session"
updated_at: datetime
formatdate-time
zone_id: str
archived_at: Optional[datetime]
formatdate-time
latest_version: Optional[int]

Human-readable version number of the latest version (e.g., 1, 2, 3)

latest_version_id: Optional[str]
updated_by: Optional[str]
class PolicySetDraft: …
created_at: datetime
formatdate-time
entries: List[PolicySetManifestEntry]
policy_id: str
policy_version_id: str
sha: Optional[str]

SHA-256 of the policy version content, populated by the server

policy_set_id: str
schema_version: str
updated_at: datetime
formatdate-time
updated_by: str
base_version_id: Optional[str]

ID of the policy set version this draft was hydrated from. Null when the draft was created without an existing version.

description: Optional[str]
name: Optional[str]
warnings: Optional[List[Warning]]

Warnings about manifest entries that would prevent creating a version from this draft. Present only when there are warnings; omitted when empty.

message: str

Human-readable description of the warning, e.g. 'validated against schema "2026-02-24", draft targets "2026-03-16"' or 'policy version is archived'.

policy_id: str
policy_version_id: str
type: Literal["policy_version_archived", "schema_version_mismatch"]
Accepts one of the following:
"policy_version_archived"
"schema_version_mismatch"
detail: Optional[WarningDetail]

Structured detail payload. Present for warning types that carry additional context (e.g. schema_version_mismatch includes the two schema versions). Omitted when the type alone is sufficient (e.g. policy_version_archived).

draft_schema_version: Optional[str]

Schema version the draft targets. Present only for schema_version_mismatch warnings.

policy_schema_version: Optional[str]

Schema version the policy version was validated against. Present only for schema_version_mismatch warnings.

class PolicySetManifest: …
entries: List[PolicySetManifestEntry]
policy_id: str
policy_version_id: str
sha: Optional[str]

SHA-256 of the policy version content, populated by the server

class PolicySetManifestEntry: …
policy_id: str
policy_version_id: str
sha: Optional[str]

SHA-256 of the policy version content, populated by the server

class PolicySetWithBinding: …
active: Optional[bool]

Whether this policy set is currently bound to a scope

active_version: Optional[int]

Human-readable version number of the active version (e.g., 1, 2, 3)

active_version_id: Optional[str]

Public ID of the currently active (bound) version

mode: Optional[Literal["active", "shadow"]]
Accepts one of the following:
"active"
"shadow"
scope_target_id: Optional[str]
shadow_version: Optional[int]

Human-readable version number of the shadow version

shadow_version_id: Optional[str]

Public ID of the shadow (observed) version, if any

Policy SetsVersions

List versions of a policy set
zones.policy_sets.versions.list(strpolicy_set_id, VersionListParams**kwargs) -> VersionListResponse
GET/zones/{zone_id}/policy-sets/{policy_set_id}/versions
Create a new immutable policy set version
zones.policy_sets.versions.create(strpolicy_set_id, VersionCreateParams**kwargs) -> PolicySetVersion
POST/zones/{zone_id}/policy-sets/{policy_set_id}/versions
Get a specific policy set version
zones.policy_sets.versions.retrieve(strversion_id, VersionRetrieveParams**kwargs) -> PolicySetVersion
GET/zones/{zone_id}/policy-sets/{policy_set_id}/versions/{version_id}
Activate a policy set version
zones.policy_sets.versions.update(strversion_id, VersionUpdateParams**kwargs) -> PolicySetVersion
PATCH/zones/{zone_id}/policy-sets/{policy_set_id}/versions/{version_id}
Archive a policy set version
zones.policy_sets.versions.archive(strversion_id, VersionArchiveParams**kwargs) -> PolicySetVersion
DELETE/zones/{zone_id}/policy-sets/{policy_set_id}/versions/{version_id}
List policy versions in a policy set version
zones.policy_sets.versions.list_policies(strversion_id, VersionListPoliciesParams**kwargs) -> VersionListPoliciesResponse
GET/zones/{zone_id}/policy-sets/{policy_set_id}/versions/{version_id}/policies
ModelsExpand Collapse
class PolicySetVersion: …
id: str
created_at: datetime
formatdate-time
created_by: str
entries: List[PolicySetManifestEntry]
policy_id: str
policy_version_id: str
sha: Optional[str]

SHA-256 of the policy version content, populated by the server

manifest_sha: str

Hex-encoded SHA-256 of the canonicalized manifest

owner_type: Literal["platform", "customer"]

Who manages this policy set version:

  • "platform" — managed by the Keycard platform (system policy set versions).
  • "customer" — managed by the tenant (custom policy set versions).
Accepts one of the following:
"platform"
"customer"
policy_set_id: str
schema_version: str

Schema version pinned to this policy set version. Determines the Cedar schema used for evaluation when activated.

version: int
active: Optional[bool]

Whether this policy set version is currently bound with mode='active'

archived_at: Optional[datetime]
formatdate-time
archived_by: Optional[str]
attestation: Optional[AttestationStatement]

Decoded content of an Attestation JWS payload. Describes the exact policy set version composition at attestation time. This schema defines what consumers see after base64url-decoding the Attestation.payload field.

attested_at: datetime
formatdate-time
attested_by: str
key_id: str

Key ID of the signing key used to produce the attestation signature. Matches the "kid" in the JWS protected header.

manifest_sha: str

SHA-256 of the policy set version manifest. Verifiers MUST check this matches the policy_set_version.manifest_sha to detect attestation/version mismatches.

policy_set_id: str
policy_set_version: int
status: Literal["created", "re_signed"]

Event that produced this attestation. "created" is the initial attestation at version creation; "re_signed" is a re-attestation after key rotation (same content, new signature).

Accepts one of the following:
"created"
"re_signed"
type: Literal["policy_set_attestation"]

Statement type discriminator

v: Literal[1]

Statement schema version

zone_id: str