Policy Sets

List policy sets in a zone

client.Zones.PolicySets.List(ctx, zoneID, params) (*ZonePolicySetListResponse, error)

GET/zones/{zone_id}/policy-sets

Returns a paginated list of policy sets in the zone.

filter[target_type] defaults to zone, hiding principal-scoped sets (e.g. per-user bundle sets) unless explicitly widened. The deprecated filter[scope_type] is honored as an equivalent and suppresses the default; supplying both with different value sets returns 400.

ParametersExpand Collapse

zoneID string

params ZonePolicySetListParams

Active param.Field[bool]optional

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 param.Field[string]optional

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

minLength1

maxLength255

Before param.Field[string]optional

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

minLength1

maxLength255

Expand param.Field[[]string]optional

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

const ZonePolicySetListParamsExpandTotalCount ZonePolicySetListParamsExpand = "total_count"

FilterActive param.Field[bool]optional

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 param.Field[[]string]optional

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 param.Field[[]string]optional

Query param: Deprecated. Use filter[target_type] instead.

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 only. Use filter[target_type] to select user (or future) targets. 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.

Still honored for backward compatibility and suppresses the filter[target_type] zone default. Supplying both this and filter[target_type] with different value sets returns 400 Bad Request.

FilterTargetType param.Field[[]string]optional

Query param: Filter on target_type. Repeatable; repeated instances OR across values. See FilterValues in the shared spec for the full wire convention.

Allowed values: zone, user (resource and session are reserved and not yet accepted). 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.

Defaults to zone when omitted (and no deprecated equivalent parameter is supplied), so listings exclude principal-scoped elements unless explicitly widened. On listPolicies the default is skipped when filter[id] is present, so by-ID fetches resolve regardless of target.

Limit param.Field[int64]optional

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

minimum1

maximum100

Order param.Field[ZonePolicySetListParamsOrder]optional

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

const ZonePolicySetListParamsOrderAsc ZonePolicySetListParamsOrder = "asc"

const ZonePolicySetListParamsOrderDesc ZonePolicySetListParamsOrder = "desc"

Query param.Field[[]string]optional

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 param.Field[[]string]optional

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 param.Field[ZonePolicySetListParamsSort]optional

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.

const ZonePolicySetListParamsSortCreatedAt ZonePolicySetListParamsSort = "created_at"

const ZonePolicySetListParamsSortStatus ZonePolicySetListParamsSort = "status"

XAPIVersion param.Field[string]optional

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

XClientRequestID param.Field[string]optional

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

formatuuid

ReturnsExpand Collapse

type ZonePolicySetListResponse struct{…}

Items []PolicySetWithBinding

Active booloptional

Whether this policy set is currently bound to a scope

ActiveVersion int64optional

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

ActiveVersionID stringoptional

Public ID of the currently active (bound) version

Mode stringoptional

Accepts one of the following:

const PolicySetWithBindingModeActive PolicySetWithBindingMode = "active"

const PolicySetWithBindingModeShadow PolicySetWithBindingMode = "shadow"

DeprecatedScopeTargetID stringoptional

Deprecated. Use target_id instead. Carries the active binding's target; null when unbound.

ShadowVersion int64optional

Human-readable version number of the shadow version

ShadowVersionID stringoptional

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

TargetID stringoptional

Target entity ID. Equals zone_id for zone-targeted sets; the principal identifier for principal-scoped sets. Null only for legacy non-zone sets that predate target tracking.

Pagination ZonePolicySetListResponsePagination

Cursor-based pagination metadata returned alongside a list of results

AfterCursor string

An opaque cursor used for paginating through a list of results

minLength1

maxLength255

BeforeCursor string

An opaque cursor used for paginating through a list of results

minLength1

maxLength255

TotalCount int64optional

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

List policy sets in a zone

package main

import (
  "context"
  "fmt"

  "github.com/keycardai/keycard-go"
)

func main() {
  client := keycard.NewClient(

  )
  policySets, err := client.Zones.PolicySets.List(
    context.TODO(),
    "zone_id",
    keycard.ZonePolicySetListParams{

    },
  )
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", policySets.Items)
}

{
  "items": [
    {
      "id": "id",
      "created_at": "2019-12-27T18:11:19.117Z",
      "created_by": "created_by",
      "name": "name",
      "owner_type": "platform",
      "scope_type": "zone",
      "target_type": "zone",
      "updated_at": "2019-12-27T18:11:19.117Z",
      "zone_id": "zone_id",
      "archived_at": "2019-12-27T18:11:19.117Z",
      "latest_version": 0,
      "latest_version_id": "latest_version_id",
      "updated_by": "updated_by",
      "active": true,
      "active_version": 0,
      "active_version_id": "active_version_id",
      "mode": "active",
      "scope_target_id": "scope_target_id",
      "shadow_version": 0,
      "shadow_version_id": "shadow_version_id",
      "target_id": "target_id"
    }
  ],
  "pagination": {
    "after_cursor": "x",
    "before_cursor": "x",
    "total_count": 0
  }
}

Returns Examples

{
  "items": [
    {
      "id": "id",
      "created_at": "2019-12-27T18:11:19.117Z",
      "created_by": "created_by",
      "name": "name",
      "owner_type": "platform",
      "scope_type": "zone",
      "target_type": "zone",
      "updated_at": "2019-12-27T18:11:19.117Z",
      "zone_id": "zone_id",
      "archived_at": "2019-12-27T18:11:19.117Z",
      "latest_version": 0,
      "latest_version_id": "latest_version_id",
      "updated_by": "updated_by",
      "active": true,
      "active_version": 0,
      "active_version_id": "active_version_id",
      "mode": "active",
      "scope_target_id": "scope_target_id",
      "shadow_version": 0,
      "shadow_version_id": "shadow_version_id",
      "target_id": "target_id"
    }
  ],
  "pagination": {
    "after_cursor": "x",
    "before_cursor": "x",
    "total_count": 0
  }
}