Skip to main content

Policies

IAM documents a project attaches to agents and triggers, narrowing what their runs may do.

Overview​

A policy is a named document of Allow and Deny statements over the runtime's actions (memories:CreateMemory, tools:CallTool, …), scoped to one project. On its own it grants nothing: it takes effect where a resource names it in policy_ids.

  • An agent's policy_ids caps every generation: the run acts as the caller's permissions intersected with the policies.
  • A trigger's policy_ids is what a firing acts under.
  • An eval, decider, ingestion rule, memory rule or playbook acts under its required policy_ids, whoever starts its work.

A policy something names cannot be deleted (409 POLICY_HAS_DEPENDENTS), and whoever writes the carrier must hold every grant its policies carry (403 POLICY_GRANT_NOT_HELD).

Limit what an agent may do writes one and attaches it to an agent.

This module is a verbatim mirror of the runtime: every field, method, status code and error shape is the runtime's own, re-rooted under the project in the path.

One answer is naturali's own: changing or deleting the policy naturali deploys for managed conversion, which lets its ingestion rules run the converter, answers 403 MANAGED_RESOURCE_READ_ONLY, on every path the runtime writes through, not only these routes.

See the OpenAPI spec for the full endpoint and schema reference, or browse it rendered under API Reference → Policies.

Data Model​

Policy​

FieldTypeDescription
idstringPublic policy ID (pol_ prefix)
project_idstring, nullableThe project the policy belongs to; null for a global policy.
namestring, nullable
descriptionstring, nullable
documentobject
created_atstring (date-time)
updated_atstring (date-time)

Statement​

FieldTypeDescription
effectAllow | Deny
actionstring[]
resourcestring[]Resource SRN patterns. Omitted, an Allow in a project policy matches every resource of the policy's project (srn:<project_id>:*:*); anywhere else it matches every resource.
conditionobjectOptional condition block. Keys are condition operators (e.g. StringEquals) mapping to context-key/value maps; evaluated by the policy compiler. A context key must be one the platform supplies — iam:ResourceType, iam:ResourceTag/<tag> (the tag on the target resource) or iam:RequestTag/<key> (the tag value the request writes) — because an unknown key is absent from the evaluation context, so a Deny naming one would never deny. The tag name after the slash is opaque and unconstrained. Operator and context keys are matched by exact string and are never case-converted, so they round-trip exactly as written: iam:ResourceTag/cost_center selects the tag cost_center, not costCenter.
denialobjectOn a Deny only: what a request this statement denies answers in place of FORBIDDEN. code is one the deployment declares; meta is added beside action, resource and denied_by. Only an unrestricted admin writes a policy carrying one (403 POLICY_DENIAL_RESERVED).

Key Concepts​

A policy belongs to the project in the path​

POST /v1/projects/{project_id}/policies creates a policy of that project, and its Allow statements may name only that project's resources (srn:<project_id>:<type>:<id>), else 400. An Allow without resource grants every resource of the project (srn:<project_id>:*:*); a Deny without one denies everywhere. A list returns the project's own policies.

naturali create-policy \
--project-id "$PROJECT" \
--name read-only-memories \
--document "{
\"statement\": [
{ \"effect\": \"Allow\", \"action\": [\"memories:*\"], \"resource\": [\"srn:$PROJECT:*:*\"] },
{ \"effect\": \"Deny\", \"action\": [\"memories:CreateMemory\", \"memories:UpdateMemory\"] }
]
}"

A Deny always wins over an Allow. A condition reads iam:ResourceType, iam:ResourceTag/<tag>, matched against a resource's tags (see Tags), or iam:RequestTag/<tag>, the value a write sets for that tag; a read sets none. A formation that computes a tag's value is refused under such a condition (Formations).

Attaching one needs its grants​

Writing policy_ids on an agent or a trigger is refused unless the writer holds every grant of the policies it names, so a policy never lends its attacher more than the attacher has. The same holds for an API key narrowed by capabilities: its runtime grant is its capabilities.

A policy in use cannot be deleted​

DELETE /v1/projects/{project_id}/policies/{policy_id} answers 409 POLICY_HAS_DEPENDENTS while a trigger or an agent names the policy in its policy_ids. Detach it first.

Policies cover the runtime's modules, not naturali's own​

A policy governs the mirrored modules: agents, tools, memories, knowledge, triggers and the rest. The routes naturali serves itself (channels, webhooks, addresses, projects, users, API keys) are governed by project membership and by an API key's capabilities, never by a policy.

Declaring one in a formation​

A formation template may declare a policy resource and reference it from an agent's or a trigger's policy_ids, so a stack ships with the narrowing it needs.