Skip to main content
POST/policies/validate

Validate Policy

Validates a candidate policy bundle body against all schema and operator rules without persisting any state.

Returns the validation outcome — pass, fail with error codes, or warnings — including specific errors for unknown operators (K9O_POLICY_UNKNOWN_OPERATOR), exceeded nesting depth (K9O_POLICY_NESTING_TOO_DEEP), unknown context fields (K9O_POLICY_UNKNOWN_CONTEXT_FIELD), and bundle invalidity (K9O_POLICY_BUNDLE_INVALID).

Requires PROJECT_ADMIN.

Parameters
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.

Responses
HTTPK9O CodeDescription
200Success
400K9O_POLICY_NESTING_TOO_DEEPThe candidate policy rule exceeds the maximum nesting depth of 20; reduce the rule nesting before re-validating.
400K9O_POLICY_UNKNOWN_OPERATORThe candidate 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 candidate 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 run policy validation.
422K9O_POLICY_BUNDLE_INVALIDThe candidate bundle is structurally valid but fails domain-level validation such as a referential schema mismatch.
Response body (200)
data *object

The result of a validation that passed.

Nothing is saved.

valid *true

Always true.

A bundle that fails validation gets an error response instead, naming the problem.

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

Showing example in TypeScript

Request example
{
  "policy": {
    "collections": {},
    "storage": {}
  }
}
Response example (200)
{
  "data": {
    "valid": true
  }
}

More in Policy & Approvals