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_idscaps every generation: the run acts as the caller's permissions intersected with the policies. - A trigger's
policy_idsis 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
| Field | Type | Description |
|---|---|---|
id | string | Public policy ID (pol_ prefix) |
project_id | string, nullable | The project the policy belongs to; null for a global policy. |
name | string, nullable | |
description | string, nullable | |
document | object | |
created_at | string (date-time) | |
updated_at | string (date-time) |
Statement
| Field | Type | Description |
|---|---|---|
effect | Allow | Deny | |
action | string[] | |
resource | string[] | 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. |
condition | object | Optional 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. |
denial | object | On 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.
- CLI
- SDK
- curl
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\"] }
]
}"
const { data: policy } = await naturali.policies.createPolicy({
path: { project_id: process.env.PROJECT! },
body: {
name: 'read-only-memories',
document: {
statement: [
{
effect: 'Allow',
action: ['memories:*'],
resource: [`srn:${process.env.PROJECT}:*:*`],
},
{
effect: 'Deny',
action: ['memories:CreateMemory', 'memories:UpdateMemory'],
},
],
},
},
});
curl -X POST "https://api.naturali.ai/v1/projects/$PROJECT/policies" \
-H "Authorization: Bearer $NATURALI_TOKEN" \
-H "Content-Type: application/json" \
-d "{
\"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.