Skip to main content
PATCH/policies/{bundleId}

Update Policy Draft

Updates the policy document of a draft bundle.

Only draft-status bundles are editable; attempts to edit a published or superseded bundle return K9O_POLICY_PUBLISH_CONFLICT (409).

Requires PROJECT_ADMIN.

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
policy *object

The policy document.

Every block is optional.

A key other than these seven is refused with 422 K9O_POLICY_BUNDLE_INVALID and reason unknown_surface.

collectionsany

Row-level rules per collection, keyed by collection name.

Each collection holds actions, keyed by select, insert, update or delete, and each action holds a rule: true, false, or a JSON predicate such as {"eq": ["row.owner_id", "subject.id"]}.

An action with no rule is denied.

Publishing compiles these rules into the database's row-level security.

One of: object
or: null
storageany

Storage rules per bucket, keyed by bucket name.

They are checked on each storage request.

One of: object
or: null
toolsany

Rules for tool calls, keyed by the tool's platform name or *.

Each tool takes invoke.

Each verb takes a rule list: a rule name from rules, an array of names, or a nested {"all": [...]} / {"any": [...]} expression of names.

One of: object
or: null
functionsany

Rules for functions, keyed by function name, <module>:* or *.

Each function takes invoke, and actions with deploy, read and delete.

Each verb takes a rule list: a rule name from rules, an array of names, or a nested {"all": [...]} / {"any": [...]} expression of names.

Only invoke is enforced; a rule on any other verb is refused with 422 K9O_POLICY_BUNDLE_INVALID and reason not_enforced.

One of: object
or: null
secretsany

Rules for secrets: actions.create, and per secret id (sec_...) or * a reveal verb.

Each verb takes a rule list: a rule name from rules, an array of names, or a nested {"all": [...]} / {"any": [...]} expression of names.

One of: object
or: null
streamsany

Rules for streams, keyed by stream name or *.

Each stream takes actions with create, read, delete, publish, subscribe and replay.

Each verb takes a rule list: a rule name from rules, an array of names, or a nested {"all": [...]} / {"any": [...]} expression of names.

One of: object
or: null
analyticsany

Rules for analytics datasets, keyed by dataset slug or *.

Each dataset takes query.

Each verb takes a rule list: a rule name from rules, an array of names, or a nested {"all": [...]} / {"any": [...]} expression of names.

One of: object
or: null
rulesany

The named-rule catalogue, an array of rule objects that the unit surfaces refer to by name.

Each rule has a name and a when predicate, plus either action (allow or deny) or requires_approval_from (an approver set).

With requires_approval_from a rule may also set recommendation, expires_after (ISO 8601 duration), escalation (an array of {escalate_after, to}), delegation_enabled and delegation_max_ttl.

requires_proof ({max_age, min_tier}) asks for a fresh step-up.

Omit it or send null for no catalogue.

editorMode"visual" | "json" | "unspecified"

The editor the bundle was written in, so a console can reopen it in the same one: visual, json, or unspecified.

Responses
HTTPK9O CodeDescription
200Success
400K9O_POLICY_NESTING_TOO_DEEPThe updated policy rule exceeds the maximum nesting depth of 20.
400K9O_POLICY_UNKNOWN_OPERATORThe updated bundle contains a policy rule with an operator name not in the supported vocabulary.
400K9O_POLICY_UNKNOWN_CONTEXT_FIELDA subject or resource operand path in the updated 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 update a policy bundle.
403K9O_POLICY_AUTHORING_AUTHORITY_INSUFFICIENTThe caller's role is not authorised to author the approval rules in the updated bundle for the targeted collection and operation scope.
404K9O_POLICY_NOT_FOUNDNo policy bundle with the supplied identifier exists in this project.
409K9O_POLICY_PUBLISH_CONFLICTThe bundle is in a published or superseded state and cannot be edited; only draft bundles are mutable.
Response body (200)
data *object

A policy bundle: the policy document, its named rules and where it is in its lifecycle.

id *string

The bundle id (pol_...; bundles created before the rename keep a bnd_... id).

projectId *string

The project the bundle belongs to (proj_...).

status *"draft" | "published" | "superseded"

draft can be edited, deleted and published. published is the bundle in force; a project has at most one. superseded was published and has been replaced or deactivated.

policy *object

The policy document as stored: collections, storage, tools, functions, secrets, streams and analytics, each present only when it was sent.

rulesobject[]

The named-rule catalogue.

Present only when the bundle has one.

createdBy *string

The id of the user who created the bundle (usr_...).

createdAt *string <date-time>

When the bundle was created.

publishedAt *any

When the bundle was published.

Null for a draft.

One of: string <date-time>
or: null
supersededAt *any

When the bundle stopped being in force.

Null unless status is superseded.

One of: string <date-time>
or: null
supersededBy *any

The id of the bundle that replaced this one.

Null when nothing replaced it.

One of: string
or: null
source *"rest" | "migration" | "cli"

How the bundle was created: rest through this API, migration by a platform migration, cli from the CLI.

editorMode *"visual" | "json" | "unspecified"

The editor the bundle was written in, so a console can reopen it in the same one: visual, json, or unspecified.

supersededReason *any

The reason given when the bundle was deactivated.

Null otherwise.

One of: string
or: null
pendingChangeId *any

The id of a queued publish for this bundle that is waiting for an approver (apr_...).

Set on the list and single-bundle reads; null when nothing is queued, and always null in create, update and current-policy responses.

One of: string
or: null
meta *any
TypeScript
// const k9o = new K9o({ orgSlug: 'playground', projectSlug: 'storefront', apiKey: 'k9o_…' })
const { data } = await k9o.policies.update('pol_demo00000001', {
  policy: {
    collections: {},
    storage: {}
  },
  editorMode: 'visual'
})

Showing example in TypeScript

Request example
{
  "policy": {
    "collections": {},
    "storage": {}
  },
  "editorMode": "visual"
}
Response example (200)
{
  "data": {
    "id": "string",
    "projectId": "string",
    "status": "draft",
    "rules": [],
    "createdBy": "string",
    "createdAt": "string",
    "publishedAt": "string",
    "supersededAt": "string",
    "supersededBy": "string",
    "source": "rest",
    "editorMode": "visual",
    "supersededReason": "string",
    "pendingChangeId": "string"
  }
}

More in Policy & Approvals