# Policy Sets

## List

`client.zones.policySets.list(stringzoneID, PolicySetListParamsparams?, RequestOptionsoptions?): PolicySetListResponse`

**get** `/zones/{zone_id}/policy-sets`

List policy sets in a zone

### Parameters

- `zoneID: string`

- `params: PolicySetListParams`

  - `active?: boolean`

    Query param: **Deprecated.** Use `filter[active]` instead.

    Filter by active binding status. When `true`, returns only policy sets with an active binding. When `false`, returns only policy sets without one. Omit to return all.

    Still honored for backward compatibility. Supplying both `active` and `filter[active]` with conflicting values returns `400 Bad Request`.

  - `after?: string`

    Query param: Cursor for forward pagination. Returned in `Pagination.after_cursor`. Mutually exclusive with `before`.

  - `before?: string`

    Query param: Cursor for backward pagination. Returned in `Pagination.before_cursor`. Mutually exclusive with `after`.

  - `expand?: Array<"total_count">`

    Query param: Opt-in to additional response fields. Repeatable; matches the `expand[]` convention used across the Keycard API.

    - `"total_count"`

  - `filterActive?: boolean`

    Query param: Filter by active binding status. When `true`, returns only policy sets with an active binding. When `false`, returns only policy sets without one. Omit to return all.

  - `filterOwnerType?: Array<string>`

    Query param: Filter on `owner_type`. Repeatable; repeated instances OR across values
    (e.g. `?filter[owner_type]=platform&filter[owner_type]=customer` matches
    either). See `FilterValues` in the shared spec for the full wire
    convention.

    Allowed values: `platform`, `customer`. Unknown values return 400 with
    the list of allowed values. Comma-separated single values
    (e.g. `?filter[owner_type]=platform,customer`) are rejected with a 400
    pointing at the repeated-parameter OR form.

    Note: the allowed-value enum is enforced in the handler (not as an
    OpenAPI `items.enum`) so the server can return a targeted error for
    the comma-AND form instead of a generic "not in allowed values"
    response.

  - `filterScopeType?: Array<string>`

    Query param: Filter on `scope_type` (policy sets only). Repeatable; repeated
    instances OR across values. See `FilterValues` in the shared spec
    for the full wire convention.

    Allowed values: `zone`, `resource`, `user`, `session`. Unknown values
    return 400 with the list of allowed values. Comma-separated single
    values are rejected with a 400 pointing at the repeated-parameter OR
    form.

    Note: the allowed-value enum is enforced in the handler (not as an
    OpenAPI `items.enum`) so the server can return a targeted error for
    the comma-AND form instead of a generic "not in allowed values"
    response.

  - `limit?: number`

    Query param: Maximum number of items to return per page.

  - `order?: "asc" | "desc"`

    Query param: Sort direction. Default is desc (newest first).

    - `"asc"`

    - `"desc"`

  - `query?: Array<string>`

    Query param: Case-insensitive substring search across all searchable fields of the resource. For policies that is `name` and `description`; for policy sets that is `name`. Repeatable; if multiple terms are supplied they are OR-ed.

  - `queryName?: Array<string>`

    Query param: Case-insensitive substring search on `name`. Repeatable; if multiple terms are supplied they are OR-ed (any matching term returns the row).

  - `sort?: "created_at" | "status"`

    Query param: Field to sort by. `created_at` (default) sorts by creation date.
    `status` sorts active-first, then by creation date within each
    group. When `sort=status`, only descending order and forward
    pagination are supported; `order=asc` or `before` cursors
    return 400.

    - `"created_at"`

    - `"status"`

  - `xAPIVersion?: string`

    Header param: API version header (date-based, e.g. 2026-02-01)

  - `xClientRequestID?: string`

    Header param: Unique request identifier specified by the originating caller and passed along by proxies.

### Returns

- `PolicySetListResponse`

  - `items: Array<PolicySetWithBinding>`

    - `active?: boolean`

      Whether this policy set is currently bound to a scope

    - `active_version?: number | null`

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

    - `active_version_id?: string | null`

      Public ID of the currently active (bound) version

    - `mode?: "active" | "shadow" | null`

      - `"active"`

      - `"shadow"`

    - `scope_target_id?: string | null`

    - `shadow_version?: number | null`

      Human-readable version number of the shadow version

    - `shadow_version_id?: string | null`

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

  - `pagination: Pagination`

    Cursor-based pagination metadata returned alongside a list of results

    - `after_cursor: string | null`

      An opaque cursor used for paginating through a list of results

    - `before_cursor: string | null`

      An opaque cursor used for paginating through a list of results

    - `total_count?: number`

      Total number of items across all pages. Only present when the request includes ?expand[]=total_count.

### Example

```typescript
import KeycardAPI from '@keycardai/api';

const client = new KeycardAPI();

const policySets = await client.zones.policySets.list('zone_id');

console.log(policySets.items);
```

## Create

`client.zones.policySets.create(stringzoneID, PolicySetCreateParamsparams, RequestOptionsoptions?): PolicySetWithBinding`

**post** `/zones/{zone_id}/policy-sets`

Creates an unbound policy set. Use updatePolicySet to bind after creating a version.

### Parameters

- `zoneID: string`

- `params: PolicySetCreateParams`

  - `name: string`

    Body param

  - `scope_type?: "zone" | "resource" | "user" | "session"`

    Body param: 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.

    - `"zone"`

    - `"resource"`

    - `"user"`

    - `"session"`

  - `xAPIVersion?: string`

    Header param: API version header (date-based, e.g. 2026-02-01)

  - `xClientRequestID?: string`

    Header param: Unique request identifier specified by the originating caller and passed along by proxies.

### Returns

- `PolicySetWithBinding extends PolicySet`

  - `active?: boolean`

    Whether this policy set is currently bound to a scope

  - `active_version?: number | null`

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

  - `active_version_id?: string | null`

    Public ID of the currently active (bound) version

  - `mode?: "active" | "shadow" | null`

    - `"active"`

    - `"shadow"`

  - `scope_target_id?: string | null`

  - `shadow_version?: number | null`

    Human-readable version number of the shadow version

  - `shadow_version_id?: string | null`

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

### Example

```typescript
import KeycardAPI from '@keycardai/api';

const client = new KeycardAPI();

const policySetWithBinding = await client.zones.policySets.create('zone_id', { name: 'name' });

console.log(policySetWithBinding);
```

## Retrieve

`client.zones.policySets.retrieve(stringpolicySetID, PolicySetRetrieveParamsparams, RequestOptionsoptions?): PolicySetWithBinding`

**get** `/zones/{zone_id}/policy-sets/{policy_set_id}`

Returns the policy set with current binding information.

### Parameters

- `policySetID: string`

- `params: PolicySetRetrieveParams`

  - `zone_id: string`

    Path param: The zone identifier

  - `xAPIVersion?: string`

    Header param: API version header (date-based, e.g. 2026-02-01)

  - `xClientRequestID?: string`

    Header param: Unique request identifier specified by the originating caller and passed along by proxies.

### Returns

- `PolicySetWithBinding extends PolicySet`

  - `active?: boolean`

    Whether this policy set is currently bound to a scope

  - `active_version?: number | null`

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

  - `active_version_id?: string | null`

    Public ID of the currently active (bound) version

  - `mode?: "active" | "shadow" | null`

    - `"active"`

    - `"shadow"`

  - `scope_target_id?: string | null`

  - `shadow_version?: number | null`

    Human-readable version number of the shadow version

  - `shadow_version_id?: string | null`

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

### Example

```typescript
import KeycardAPI from '@keycardai/api';

const client = new KeycardAPI();

const policySetWithBinding = await client.zones.policySets.retrieve('policy_set_id', {
  zone_id: 'zone_id',
});

console.log(policySetWithBinding);
```

## Update

`client.zones.policySets.update(stringpolicySetID, PolicySetUpdateParamsparams, RequestOptionsoptions?): PolicySetWithBinding`

**patch** `/zones/{zone_id}/policy-sets/{policy_set_id}`

Update metadata or manage binding. Set active=true to bind, active=false to unbind.

### Parameters

- `policySetID: string`

- `params: PolicySetUpdateParams`

  - `zone_id: string`

    Path param: The zone identifier

  - `name?: string`

    Body param

  - `ifMatch?: string`

    Header param: ETag value from a previous GET/POST/PATCH response. When provided, the update only succeeds if the resource has not been modified; otherwise 412 Precondition Failed is returned.

  - `xAPIVersion?: string`

    Header param: API version header (date-based, e.g. 2026-02-01)

  - `xClientRequestID?: string`

    Header param: Unique request identifier specified by the originating caller and passed along by proxies.

### Returns

- `PolicySetWithBinding extends PolicySet`

  - `active?: boolean`

    Whether this policy set is currently bound to a scope

  - `active_version?: number | null`

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

  - `active_version_id?: string | null`

    Public ID of the currently active (bound) version

  - `mode?: "active" | "shadow" | null`

    - `"active"`

    - `"shadow"`

  - `scope_target_id?: string | null`

  - `shadow_version?: number | null`

    Human-readable version number of the shadow version

  - `shadow_version_id?: string | null`

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

### Example

```typescript
import KeycardAPI from '@keycardai/api';

const client = new KeycardAPI();

const policySetWithBinding = await client.zones.policySets.update('policy_set_id', {
  zone_id: 'zone_id',
});

console.log(policySetWithBinding);
```

## Archive

`client.zones.policySets.archive(stringpolicySetID, PolicySetArchiveParamsparams, RequestOptionsoptions?): PolicySetWithBinding`

**delete** `/zones/{zone_id}/policy-sets/{policy_set_id}`

Archive a policy set

### Parameters

- `policySetID: string`

- `params: PolicySetArchiveParams`

  - `zone_id: string`

    Path param: The zone identifier

  - `ifMatch?: string`

    Header param: ETag value from a previous GET/POST/PATCH response. When provided, the update only succeeds if the resource has not been modified; otherwise 412 Precondition Failed is returned.

  - `xAPIVersion?: string`

    Header param: API version header (date-based, e.g. 2026-02-01)

  - `xClientRequestID?: string`

    Header param: Unique request identifier specified by the originating caller and passed along by proxies.

### Returns

- `PolicySetWithBinding extends PolicySet`

  - `active?: boolean`

    Whether this policy set is currently bound to a scope

  - `active_version?: number | null`

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

  - `active_version_id?: string | null`

    Public ID of the currently active (bound) version

  - `mode?: "active" | "shadow" | null`

    - `"active"`

    - `"shadow"`

  - `scope_target_id?: string | null`

  - `shadow_version?: number | null`

    Human-readable version number of the shadow version

  - `shadow_version_id?: string | null`

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

### Example

```typescript
import KeycardAPI from '@keycardai/api';

const client = new KeycardAPI();

const policySetWithBinding = await client.zones.policySets.archive('policy_set_id', {
  zone_id: 'zone_id',
});

console.log(policySetWithBinding);
```

## Domain Types

### Attestation

- `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: string`

    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: string`

    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: string`

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

### Attestation Statement

- `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: string`

  - `attested_by: string`

  - `key_id: string`

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

  - `manifest_sha: string`

    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: string`

  - `policy_set_version: number`

  - `status: "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).

    - `"created"`

    - `"re_signed"`

  - `type: "policy_set_attestation"`

    Statement type discriminator

    - `"policy_set_attestation"`

  - `v: 1`

    Statement schema version

    - `1`

  - `zone_id: string`

### Policy Set

- `PolicySet`

  - `id: string`

  - `created_at: string`

  - `created_by: string`

  - `name: string`

  - `owner_type: "platform" | "customer"`

    Who manages this policy set:

    - `"platform"` — managed by the Keycard platform (system policies).
    - `"customer"` — managed by the tenant (custom policies).

    - `"platform"`

    - `"customer"`

  - `scope_type: "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.

    - `"zone"`

    - `"resource"`

    - `"user"`

    - `"session"`

  - `updated_at: string`

  - `zone_id: string`

  - `archived_at?: string | null`

  - `latest_version?: number | null`

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

  - `latest_version_id?: string | null`

  - `updated_by?: string | null`

### Policy Set Draft

- `PolicySetDraft`

  - `created_at: string`

  - `manifest: PolicySetManifest`

    - `entries: Array<PolicySetManifestEntry>`

      - `policy_id: string`

      - `policy_version_id: string`

      - `sha?: string`

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

  - `policy_set_id: string`

  - `schema_version: string`

  - `updated_at: string`

  - `updated_by: string`

  - `base_version_id?: string | null`

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

  - `description?: string | null`

  - `name?: string | null`

  - `warnings?: Array<Warning>`

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

    - `message: string`

      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: string`

    - `policy_version_id: string`

    - `type: "policy_version_archived" | "schema_version_mismatch"`

      - `"policy_version_archived"`

      - `"schema_version_mismatch"`

    - `detail?: Detail`

      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?: string`

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

      - `policy_schema_version?: string`

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

### Policy Set Manifest

- `PolicySetManifest`

  - `entries: Array<PolicySetManifestEntry>`

    - `policy_id: string`

    - `policy_version_id: string`

    - `sha?: string`

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

### Policy Set Manifest Entry

- `PolicySetManifestEntry`

  - `policy_id: string`

  - `policy_version_id: string`

  - `sha?: string`

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

### Policy Set With Binding

- `PolicySetWithBinding extends PolicySet`

  - `active?: boolean`

    Whether this policy set is currently bound to a scope

  - `active_version?: number | null`

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

  - `active_version_id?: string | null`

    Public ID of the currently active (bound) version

  - `mode?: "active" | "shadow" | null`

    - `"active"`

    - `"shadow"`

  - `scope_target_id?: string | null`

  - `shadow_version?: number | null`

    Human-readable version number of the shadow version

  - `shadow_version_id?: string | null`

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

# Versions

## List

`client.zones.policySets.versions.list(stringpolicySetID, VersionListParamsparams, RequestOptionsoptions?): VersionListResponse`

**get** `/zones/{zone_id}/policy-sets/{policy_set_id}/versions`

List versions of a policy set

### Parameters

- `policySetID: string`

- `params: VersionListParams`

  - `zone_id: string`

    Path param: The zone identifier

  - `after?: string`

    Query param: Cursor for forward pagination. Returned in `Pagination.after_cursor`. Mutually exclusive with `before`.

  - `before?: string`

    Query param: Cursor for backward pagination. Returned in `Pagination.before_cursor`. Mutually exclusive with `after`.

  - `expand?: Array<"total_count">`

    Query param: Opt-in to additional response fields. Repeatable; matches the `expand[]` convention used across the Keycard API.

    - `"total_count"`

  - `limit?: number`

    Query param: Maximum number of items to return per page.

  - `order?: "asc" | "desc"`

    Query param: Sort direction. Default is desc (newest first).

    - `"asc"`

    - `"desc"`

  - `sort?: "created_at"`

    Query param: Field to sort by.

    - `"created_at"`

  - `xAPIVersion?: string`

    Header param: API version header (date-based, e.g. 2026-02-01)

  - `xClientRequestID?: string`

    Header param: Unique request identifier specified by the originating caller and passed along by proxies.

### Returns

- `VersionListResponse`

  - `items: Array<PolicySetVersion>`

    - `id: string`

    - `created_at: string`

    - `created_by: string`

    - `manifest: PolicySetManifest`

      - `entries: Array<PolicySetManifestEntry>`

        - `policy_id: string`

        - `policy_version_id: string`

        - `sha?: string`

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

    - `manifest_sha: string`

      Hex-encoded SHA-256 of the canonicalized manifest

    - `owner_type: "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).

      - `"platform"`

      - `"customer"`

    - `policy_set_id: string`

    - `schema_version: string`

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

    - `version: number`

    - `active?: boolean`

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

    - `archived_at?: string | null`

    - `archived_by?: string | null`

    - `attestation?: AttestationStatement | null`

      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: string`

      - `attested_by: string`

      - `key_id: string`

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

      - `manifest_sha: string`

        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: string`

      - `policy_set_version: number`

      - `status: "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).

        - `"created"`

        - `"re_signed"`

      - `type: "policy_set_attestation"`

        Statement type discriminator

        - `"policy_set_attestation"`

      - `v: 1`

        Statement schema version

        - `1`

      - `zone_id: string`

  - `pagination: Pagination`

    Cursor-based pagination metadata returned alongside a list of results

    - `after_cursor: string | null`

      An opaque cursor used for paginating through a list of results

    - `before_cursor: string | null`

      An opaque cursor used for paginating through a list of results

    - `total_count?: number`

      Total number of items across all pages. Only present when the request includes ?expand[]=total_count.

### Example

```typescript
import KeycardAPI from '@keycardai/api';

const client = new KeycardAPI();

const versions = await client.zones.policySets.versions.list('policy_set_id', {
  zone_id: 'zone_id',
});

console.log(versions.items);
```

## Create

`client.zones.policySets.versions.create(stringpolicySetID, VersionCreateParamsparams, RequestOptionsoptions?): PolicySetVersion`

**post** `/zones/{zone_id}/policy-sets/{policy_set_id}/versions`

Validates the manifest, computes SHA, and creates an immutable version snapshot.

### Parameters

- `policySetID: string`

- `params: VersionCreateParams`

  - `zone_id: string`

    Path param: The zone identifier

  - `manifest: PolicySetManifest`

    Body param

    - `entries: Array<PolicySetManifestEntry>`

      - `policy_id: string`

      - `policy_version_id: string`

      - `sha?: string`

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

  - `schema_version: string`

    Body param: Schema version to pin to this policy set version.

  - `xAPIVersion?: string`

    Header param: API version header (date-based, e.g. 2026-02-01)

  - `xClientRequestID?: string`

    Header param: Unique request identifier specified by the originating caller and passed along by proxies.

### Returns

- `PolicySetVersion`

  - `id: string`

  - `created_at: string`

  - `created_by: string`

  - `manifest: PolicySetManifest`

    - `entries: Array<PolicySetManifestEntry>`

      - `policy_id: string`

      - `policy_version_id: string`

      - `sha?: string`

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

  - `manifest_sha: string`

    Hex-encoded SHA-256 of the canonicalized manifest

  - `owner_type: "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).

    - `"platform"`

    - `"customer"`

  - `policy_set_id: string`

  - `schema_version: string`

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

  - `version: number`

  - `active?: boolean`

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

  - `archived_at?: string | null`

  - `archived_by?: string | null`

  - `attestation?: AttestationStatement | null`

    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: string`

    - `attested_by: string`

    - `key_id: string`

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

    - `manifest_sha: string`

      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: string`

    - `policy_set_version: number`

    - `status: "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).

      - `"created"`

      - `"re_signed"`

    - `type: "policy_set_attestation"`

      Statement type discriminator

      - `"policy_set_attestation"`

    - `v: 1`

      Statement schema version

      - `1`

    - `zone_id: string`

### Example

```typescript
import KeycardAPI from '@keycardai/api';

const client = new KeycardAPI();

const policySetVersion = await client.zones.policySets.versions.create('policy_set_id', {
  zone_id: 'zone_id',
  manifest: { entries: [{ policy_id: 'policy_id', policy_version_id: 'policy_version_id' }] },
  schema_version: 'schema_version',
});

console.log(policySetVersion.id);
```

## Retrieve

`client.zones.policySets.versions.retrieve(stringversionID, VersionRetrieveParamsparams, RequestOptionsoptions?): PolicySetVersion`

**get** `/zones/{zone_id}/policy-sets/{policy_set_id}/versions/{version_id}`

Get a specific policy set version

### Parameters

- `versionID: string`

- `params: VersionRetrieveParams`

  - `zone_id: string`

    Path param: The zone identifier

  - `policy_set_id: string`

    Path param: The policy set identifier

  - `xAPIVersion?: string`

    Header param: API version header (date-based, e.g. 2026-02-01)

  - `xClientRequestID?: string`

    Header param: Unique request identifier specified by the originating caller and passed along by proxies.

### Returns

- `PolicySetVersion`

  - `id: string`

  - `created_at: string`

  - `created_by: string`

  - `manifest: PolicySetManifest`

    - `entries: Array<PolicySetManifestEntry>`

      - `policy_id: string`

      - `policy_version_id: string`

      - `sha?: string`

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

  - `manifest_sha: string`

    Hex-encoded SHA-256 of the canonicalized manifest

  - `owner_type: "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).

    - `"platform"`

    - `"customer"`

  - `policy_set_id: string`

  - `schema_version: string`

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

  - `version: number`

  - `active?: boolean`

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

  - `archived_at?: string | null`

  - `archived_by?: string | null`

  - `attestation?: AttestationStatement | null`

    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: string`

    - `attested_by: string`

    - `key_id: string`

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

    - `manifest_sha: string`

      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: string`

    - `policy_set_version: number`

    - `status: "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).

      - `"created"`

      - `"re_signed"`

    - `type: "policy_set_attestation"`

      Statement type discriminator

      - `"policy_set_attestation"`

    - `v: 1`

      Statement schema version

      - `1`

    - `zone_id: string`

### Example

```typescript
import KeycardAPI from '@keycardai/api';

const client = new KeycardAPI();

const policySetVersion = await client.zones.policySets.versions.retrieve('version_id', {
  zone_id: 'zone_id',
  policy_set_id: 'policy_set_id',
});

console.log(policySetVersion.id);
```

## Update

`client.zones.policySets.versions.update(stringversionID, VersionUpdateParamsparams, RequestOptionsoptions?): PolicySetVersion`

**patch** `/zones/{zone_id}/policy-sets/{policy_set_id}/versions/{version_id}`

Set active=true to bind this version as the active zone policy set.

### Parameters

- `versionID: string`

- `params: VersionUpdateParams`

  - `zone_id: string`

    Path param: The zone identifier

  - `policy_set_id: string`

    Path param: The policy set identifier

  - `active: true`

    Body param: Must be true. Binds this version as the active zone policy set.

    - `true`

  - `xAPIVersion?: string`

    Header param: API version header (date-based, e.g. 2026-02-01)

  - `xClientRequestID?: string`

    Header param: Unique request identifier specified by the originating caller and passed along by proxies.

### Returns

- `PolicySetVersion`

  - `id: string`

  - `created_at: string`

  - `created_by: string`

  - `manifest: PolicySetManifest`

    - `entries: Array<PolicySetManifestEntry>`

      - `policy_id: string`

      - `policy_version_id: string`

      - `sha?: string`

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

  - `manifest_sha: string`

    Hex-encoded SHA-256 of the canonicalized manifest

  - `owner_type: "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).

    - `"platform"`

    - `"customer"`

  - `policy_set_id: string`

  - `schema_version: string`

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

  - `version: number`

  - `active?: boolean`

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

  - `archived_at?: string | null`

  - `archived_by?: string | null`

  - `attestation?: AttestationStatement | null`

    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: string`

    - `attested_by: string`

    - `key_id: string`

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

    - `manifest_sha: string`

      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: string`

    - `policy_set_version: number`

    - `status: "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).

      - `"created"`

      - `"re_signed"`

    - `type: "policy_set_attestation"`

      Statement type discriminator

      - `"policy_set_attestation"`

    - `v: 1`

      Statement schema version

      - `1`

    - `zone_id: string`

### Example

```typescript
import KeycardAPI from '@keycardai/api';

const client = new KeycardAPI();

const policySetVersion = await client.zones.policySets.versions.update('version_id', {
  zone_id: 'zone_id',
  policy_set_id: 'policy_set_id',
  active: true,
});

console.log(policySetVersion.id);
```

## Archive

`client.zones.policySets.versions.archive(stringversionID, VersionArchiveParamsparams, RequestOptionsoptions?): PolicySetVersion`

**delete** `/zones/{zone_id}/policy-sets/{policy_set_id}/versions/{version_id}`

Archive a policy set version

### Parameters

- `versionID: string`

- `params: VersionArchiveParams`

  - `zone_id: string`

    Path param: The zone identifier

  - `policy_set_id: string`

    Path param: The policy set identifier

  - `xAPIVersion?: string`

    Header param: API version header (date-based, e.g. 2026-02-01)

  - `xClientRequestID?: string`

    Header param: Unique request identifier specified by the originating caller and passed along by proxies.

### Returns

- `PolicySetVersion`

  - `id: string`

  - `created_at: string`

  - `created_by: string`

  - `manifest: PolicySetManifest`

    - `entries: Array<PolicySetManifestEntry>`

      - `policy_id: string`

      - `policy_version_id: string`

      - `sha?: string`

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

  - `manifest_sha: string`

    Hex-encoded SHA-256 of the canonicalized manifest

  - `owner_type: "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).

    - `"platform"`

    - `"customer"`

  - `policy_set_id: string`

  - `schema_version: string`

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

  - `version: number`

  - `active?: boolean`

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

  - `archived_at?: string | null`

  - `archived_by?: string | null`

  - `attestation?: AttestationStatement | null`

    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: string`

    - `attested_by: string`

    - `key_id: string`

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

    - `manifest_sha: string`

      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: string`

    - `policy_set_version: number`

    - `status: "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).

      - `"created"`

      - `"re_signed"`

    - `type: "policy_set_attestation"`

      Statement type discriminator

      - `"policy_set_attestation"`

    - `v: 1`

      Statement schema version

      - `1`

    - `zone_id: string`

### Example

```typescript
import KeycardAPI from '@keycardai/api';

const client = new KeycardAPI();

const policySetVersion = await client.zones.policySets.versions.archive('version_id', {
  zone_id: 'zone_id',
  policy_set_id: 'policy_set_id',
});

console.log(policySetVersion.id);
```

## List Policies

`client.zones.policySets.versions.listPolicies(stringversionID, VersionListPoliciesParamsparams, RequestOptionsoptions?): VersionListPoliciesResponse`

**get** `/zones/{zone_id}/policy-sets/{policy_set_id}/versions/{version_id}/policies`

Returns the policy versions referenced by this policy set version's manifest as a paginated list.

### Parameters

- `versionID: string`

- `params: VersionListPoliciesParams`

  - `zone_id: string`

    Path param: The zone identifier

  - `policy_set_id: string`

    Path param: The policy set identifier

  - `after?: string`

    Query param: Cursor for forward pagination. Returned in `Pagination.after_cursor`. Mutually exclusive with `before`.

  - `before?: string`

    Query param: Cursor for backward pagination. Returned in `Pagination.before_cursor`. Mutually exclusive with `after`.

  - `expand?: Array<"total_count">`

    Query param: Opt-in to additional response fields. Repeatable; matches the `expand[]` convention used across the Keycard API.

    - `"total_count"`

  - `format?: "cedar" | "json"`

    Query param: Narrows which Cedar representation the response includes. When
    omitted, both `cedar_json` and `cedar_raw` are populated. Pass
    `json` to receive only `cedar_json`, or `cedar` to receive only
    `cedar_raw`. Callers that don't care about payload size can skip
    this parameter.

    - `"cedar"`

    - `"json"`

  - `limit?: number`

    Query param: Maximum number of items to return per page.

  - `order?: "asc" | "desc"`

    Query param: Sort direction. Default is desc (newest first).

    - `"asc"`

    - `"desc"`

  - `sort?: "created_at"`

    Query param: Field to sort by.

    - `"created_at"`

  - `xAPIVersion?: string`

    Header param: API version header (date-based, e.g. 2026-02-01)

  - `xClientRequestID?: string`

    Header param: Unique request identifier specified by the originating caller and passed along by proxies.

### Returns

- `VersionListPoliciesResponse`

  - `items: Array<PolicyVersion>`

    - `id: string`

    - `created_at: string`

    - `created_by: string`

    - `owner_type: "platform" | "customer"`

      Who manages this policy version:

      - `"platform"` — managed by the Keycard platform (system policy versions).
      - `"customer"` — managed by the tenant (custom policy versions).

      - `"platform"`

      - `"customer"`

    - `policy_id: string`

    - `schema_version: string`

      Schema version this policy was validated against when created.

    - `sha: string`

      Hex-encoded content hash

    - `version: number`

    - `zone_id: string`

    - `archived_at?: string | null`

    - `archived_by?: string | null`

    - `cedar_json?: unknown`

      Cedar policy in JSON representation. Populated by default
      and when `format=json` is passed; null when `format=cedar`
      narrows the response to the text representation only.

    - `cedar_raw?: string | null`

      Cedar policy in human-readable syntax. Populated by default
      and when `format=cedar` is passed; null when `format=json`
      narrows the response to the JSON representation only.

  - `pagination: Pagination`

    Cursor-based pagination metadata returned alongside a list of results

    - `after_cursor: string | null`

      An opaque cursor used for paginating through a list of results

    - `before_cursor: string | null`

      An opaque cursor used for paginating through a list of results

    - `total_count?: number`

      Total number of items across all pages. Only present when the request includes ?expand[]=total_count.

### Example

```typescript
import KeycardAPI from '@keycardai/api';

const client = new KeycardAPI();

const response = await client.zones.policySets.versions.listPolicies('version_id', {
  zone_id: 'zone_id',
  policy_set_id: 'policy_set_id',
});

console.log(response.items);
```

## Domain Types

### Policy Set Version

- `PolicySetVersion`

  - `id: string`

  - `created_at: string`

  - `created_by: string`

  - `manifest: PolicySetManifest`

    - `entries: Array<PolicySetManifestEntry>`

      - `policy_id: string`

      - `policy_version_id: string`

      - `sha?: string`

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

  - `manifest_sha: string`

    Hex-encoded SHA-256 of the canonicalized manifest

  - `owner_type: "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).

    - `"platform"`

    - `"customer"`

  - `policy_set_id: string`

  - `schema_version: string`

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

  - `version: number`

  - `active?: boolean`

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

  - `archived_at?: string | null`

  - `archived_by?: string | null`

  - `attestation?: AttestationStatement | null`

    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: string`

    - `attested_by: string`

    - `key_id: string`

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

    - `manifest_sha: string`

      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: string`

    - `policy_set_version: number`

    - `status: "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).

      - `"created"`

      - `"re_signed"`

    - `type: "policy_set_attestation"`

      Statement type discriminator

      - `"policy_set_attestation"`

    - `v: 1`

      Statement schema version

      - `1`

    - `zone_id: string`