Skip to main content
POST/policies/{bundleId}/publish

Publish Policy

Atomically publishes a draft bundle, activating it as the project's live policy.

It validates the bundle, marks the previously published bundle as superseded, marks the draft published, and triggers Postgres RLS recompilation.

Requires PROJECT_ADMIN.

Returns K9O_POLICY_BUNDLE_INVALID (422) if validation fails at publish time, leaving the previously published bundle active.

A rule's requires_approval_from is checked for shape only: a role nobody holds yet still publishes, and nobody can approve its cases until someone holds it.

Parameters
bundleId *path

The policy bundle id (pol_...).

The pol_ prefix may be left out.

projectSlug *path

The project's slug: the path segment after @.

It is unique within the org.

Request body
acknowledgeSelfLockoutboolean

Set to true to publish a bundle that would take away your own read access to one or more collections.

Without it such a publish is refused with 409 K9O_POLICY_SELF_LOCKOUT_UNCONFIRMED, naming the collections.

The approver sees the acknowledged lockout on the pending change.

Responses
HTTPK9O CodeDescription
202Accepted
400K9O_POLICY_NESTING_TOO_DEEPA policy rule in the bundle exceeds the maximum nesting depth of 20.
400K9O_POLICY_UNKNOWN_OPERATORThe bundle contains a policy rule with an unrecognised operator name.
400K9O_POLICY_UNKNOWN_CONTEXT_FIELDA subject or resource operand path in the bundle does not resolve to a known field.
401K9O_SESSION_EXPIREDThe caller's session token is expired or invalid; re-authenticate to continue.
403K9O_ACCESS_DENIEDThe caller does not hold PROJECT_ADMIN role, which is required to publish a policy bundle.
404K9O_POLICY_NOT_FOUNDNo policy bundle with the supplied identifier exists in this project.
409K9O_POLICY_PUBLISH_CONFLICTThe bundle is already published or superseded and cannot be re-published.
422K9O_POLICY_BUNDLE_INVALIDThe bundle fails validation at publish time, for example because a referenced schema column was dropped since the draft was created.
Response body (202)
data *object

A publish waiting for approval.

Nothing is in force yet.

pendingChangeId *string

The id of the queued publish (apr_...).

A different project admin approves or rejects it through the pending-approvals endpoints.

bundleId *string

The bundle waiting to be published (pol_...).

status *"pending_approval"

Always pending_approval: the bundle is not published until an approver accepts the change.

meta *any
TypeScript
// const k9o = new K9o({ orgSlug: 'playground', projectSlug: 'storefront', apiKey: 'k9o_…' })
const { data } = await k9o.policies.publish('pol_demo00000001', {})

Showing example in TypeScript

Request example
{
  "acknowledgeSelfLockout": false
}
Response example (202)
{
  "data": {
    "pendingChangeId": "string",
    "bundleId": "string",
    "status": "pending_approval"
  }
}

More in Policy & Approvals