KEkeycardai
PolicySets

Create a new policy set

Changed on

Creates a policy set. Supply manifest to create its first version and any new policies in the same transaction. A failure rolls back every write. Without manifest, creates a versionless set and preserves the existing response body.

Entries use manifest apply semantics with no predecessor: bare pins use each policy's latest version; supplied content reuses that version when its SHA and schema match. Omitted schema_version uses the zone default. This operation supports neither dry_run nor If-Match. Set manifest.activate: true to bind v1 to the zone's active slot in the same transaction. Requires target_type: zone (the default) and the activate permission on policy_set_bindings, in addition to the route's create permission. Omitted or false leaves the set unbound.

The ETag header is the set revision, as on GET. The manifest digest is policy_set_version.manifest_sha and the ETag of GET .../manifest.

Domain error codes: policy_set_name_conflict, policy_name_conflict, policy_not_found, policy_archived, policy_version_not_found, version_archived, schema_version_mismatch, manifest_duplicate_policy, missing_cedar_content, invalid_cedar, schema_version_unsupported, activate_requires_zone_target.

post/zones/{zone_id}/policy-sets

Request

  • Base URL
    https://docs.keycard.ai (the document declares no server; this is the origin it was published from)
  • URL
    https://docs.keycard.ai/zones/{zone_id}/policy-sets
  • Auth
    • HTTP bearer
    • or OAuth 2
      Client credentials
      Token URL: /service-account-token

Path parameters

zone_idstring required

The zone identifier

Headers

X-API-Versionstring

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

X-Client-Request-IDstring uuid

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

Request body

namestring required
scope_type'zone'

Deprecated. Use target_type instead. Only zone is accepted; use target_type for user targets.

target_type'zone' | 'user'

What this policy set targets:

  • "zone" — applies to all requests in the zone.
  • "user" — can be bound to a specific user.

Response

The newly created policy set

idstring required
zone_idstring required
namestring required
scope_type'zone' | 'resource' | 'user' | 'session' required

Deprecated. Use target_type instead. Carries the same value.

target_type'zone' | 'user' required

What this policy set targets:

  • "zone" — applies to all requests in the zone.
  • "user" — scoped to a specific user.

resource and session are reserved; legacy sets with those scopes carry them in the deprecated scope_type field.

latest_version_idstring nullable
latest_versioninteger nullable

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

archived_atstring date-time nullable
created_atstring date-time required
updated_atstring date-time required
created_bystring required
updated_bystring nullable
owner_type'platform' | 'customer' required

Who manages this policy set:

  • "platform" — managed by the Keycard platform (system policies).
  • "customer" — managed by the tenant (custom policies).
scope_target_idstring nullable

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

target_idstring nullable

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.

mode'active' | 'shadow' nullable
activeboolean

Whether this policy set is currently bound to a scope

active_version_idstring nullable

Public ID of the currently active (bound) version

active_versioninteger nullable

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

shadow_version_idstring nullable

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

shadow_versioninteger nullable

Human-readable version number of the shadow version

Changes

  • 0cfaff865771Revision changes
    • breaking

      the response property // became optional for the status

    • breaking

      the response property // became optional for the status

    • breaking

      the response property // became optional for the status

    • breaking

      the response property // became optional for the status

    • breaking

      the response property // became optional for the status

    • breaking

      the response property // became optional for the status

    • breaking

      the response property // became optional for the status

    • breaking

      the response property // became optional for the status

    • breaking

      the // response's property type changed from string to no type for status

    • breaking

      the // response's property type changed from string to no type for status

    • breaking

      the // response's property type changed from string to no type for status

    • breaking

      the // response's property type changed from string to no type for status

    • breaking

      the // response's property type changed from string to no type for status

    • breaking

      the // response's property type changed from string to no type for status

    • breaking

      the // response's property type changed from string to no type for status

    • breaking

      the // response's property type changed from string to no type for status

    • warning

      added the new not_implemented enum value to the response property for the response status

    • warning

      added the new not_implemented enum value to the response property for the response status

    • warning

      added the new not_implemented enum value to the response property for the response status

    • warning

      added the new not_implemented enum value to the response property for the response status

    • warning

      added the new not_implemented enum value to the response property for the response status

    • warning

      added the new not_implemented enum value to the response property for the response status

    • warning

      added the new not_implemented enum value to the response property for the response status

    • warning

      added the new not_implemented enum value to the response property for the response status

    • info

      added the new optional request property

    • info

      added the non-success response with the status

    • info

      added the optional property //// to the response with the status

    • info

      added the optional property //// to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added subschema #2 to the // response property anyOf list for the response status

    • info

      added subschema #2 to the // response property anyOf list for the response status

    • info

      added subschema #2 to the // response property anyOf list for the response status

    • info

      added subschema #2 to the // response property anyOf list for the response status

    • info

      added subschema #2 to the // response property anyOf list for the response status

    • info

      added subschema #2 to the // response property anyOf list for the response status

    • info

      added subschema #2 to the // response property anyOf list for the response status

    • info

      added subschema #2 to the // response property anyOf list for the response status

    • info

      removed the bad_request enum value from the // response property for the response status

    • info

      removed the bad_request enum value from the // response property for the response status

    • info

      removed the bad_request enum value from the // response property for the response status

    • info

      removed the bad_request enum value from the // response property for the response status

    • info

      removed the bad_request enum value from the // response property for the response status

    • info

      removed the bad_request enum value from the // response property for the response status

    • info

      removed the bad_request enum value from the // response property for the response status

    • info

      removed the bad_request enum value from the // response property for the response status

    • info

      removed the conflict enum value from the // response property for the response status

    • info

      removed the conflict enum value from the // response property for the response status

    • info

      removed the conflict enum value from the // response property for the response status

    • info

      removed the conflict enum value from the // response property for the response status

    • info

      removed the conflict enum value from the // response property for the response status

    • info

      removed the conflict enum value from the // response property for the response status

    • info

      removed the conflict enum value from the // response property for the response status

    • info

      removed the conflict enum value from the // response property for the response status

    • info

      removed the forbidden enum value from the // response property for the response status

    • info

      removed the forbidden enum value from the // response property for the response status

    • info

      removed the forbidden enum value from the // response property for the response status

    • info

      removed the forbidden enum value from the // response property for the response status

    • info

      removed the forbidden enum value from the // response property for the response status

    • info

      removed the forbidden enum value from the // response property for the response status

    • info

      removed the forbidden enum value from the // response property for the response status

    • info

      removed the forbidden enum value from the // response property for the response status

    • info

      removed the internal_error enum value from the // response property for the response status

    • info

      removed the internal_error enum value from the // response property for the response status

    • info

      removed the internal_error enum value from the // response property for the response status

    • info

      removed the internal_error enum value from the // response property for the response status

    • info

      removed the internal_error enum value from the // response property for the response status

    • info

      removed the internal_error enum value from the // response property for the response status

    • info

      removed the internal_error enum value from the // response property for the response status

    • info

      removed the internal_error enum value from the // response property for the response status

    • info

      removed the not_found enum value from the // response property for the response status

    • info

      removed the not_found enum value from the // response property for the response status

    • info

      removed the not_found enum value from the // response property for the response status

    • info

      removed the not_found enum value from the // response property for the response status

    • info

      removed the not_found enum value from the // response property for the response status

    • info

      removed the not_found enum value from the // response property for the response status

    • info

      removed the not_found enum value from the // response property for the response status

    • info

      removed the not_found enum value from the // response property for the response status

    • info

      removed the rate_limit_exceeded enum value from the // response property for the response status

    • info

      removed the rate_limit_exceeded enum value from the // response property for the response status

    • info

      removed the rate_limit_exceeded enum value from the // response property for the response status

    • info

      removed the rate_limit_exceeded enum value from the // response property for the response status

    • info

      removed the rate_limit_exceeded enum value from the // response property for the response status

    • info

      removed the rate_limit_exceeded enum value from the // response property for the response status

    • info

      removed the rate_limit_exceeded enum value from the // response property for the response status

    • info

      removed the rate_limit_exceeded enum value from the // response property for the response status

    • info

      removed the service_unavailable enum value from the // response property for the response status

    • info

      removed the service_unavailable enum value from the // response property for the response status

    • info

      removed the service_unavailable enum value from the // response property for the response status

    • info

      removed the service_unavailable enum value from the // response property for the response status

    • info

      removed the service_unavailable enum value from the // response property for the response status

    • info

      removed the service_unavailable enum value from the // response property for the response status

    • info

      removed the service_unavailable enum value from the // response property for the response status

    • info

      removed the service_unavailable enum value from the // response property for the response status

    • info

      removed the unauthorized enum value from the // response property for the response status

    • info

      removed the unauthorized enum value from the // response property for the response status

    • info

      removed the unauthorized enum value from the // response property for the response status

    • info

      removed the unauthorized enum value from the // response property for the response status

    • info

      removed the unauthorized enum value from the // response property for the response status

    • info

      removed the unauthorized enum value from the // response property for the response status

    • info

      removed the unauthorized enum value from the // response property for the response status

    • info

      removed the unauthorized enum value from the // response property for the response status

    • info

      removed the validation_error enum value from the // response property for the response status

    • info

      removed the validation_error enum value from the // response property for the response status

    • info

      removed the validation_error enum value from the // response property for the response status

    • info

      removed the validation_error enum value from the // response property for the response status

    • info

      removed the validation_error enum value from the // response property for the response status

    • info

      removed the validation_error enum value from the // response property for the response status

    • info

      removed the validation_error enum value from the // response property for the response status

    • info

      removed the validation_error enum value from the // response property for the response status

  • 1a0dd4d857eeRevision changes
    • breaking

      removed the enum value resource of the request property

    • breaking

      removed the enum value session of the request property

    • breaking

      removed the enum value user of the request property

    • info

      added the new optional request property

    • info

      request property deprecated

    • info

      added the optional property / to the response with the status

    • info

      response property allOf[pdp_PolicySet]/scope_type deprecated

    • info

      response property allOf[subschema #2]/scope_target_id deprecated

    • info

      added the required property //// to the response with the status