---
question: How do I write a policy, and narrow it from a workspace's access policy?
kind: task
via_web: available
via_cli: na
via_python: na
via_api: available
via_config: na
ref_web: Roles & permissions › Policies
ref_api: POST /api/iam/admin/policies
prereq: You are an owner or admin of the workspace or organization, the platform admin, or you hold `iam:CreatePolicy` there.
next:
  - /capabilities/platform/give-someone-access
  - /capabilities/platform/test-access-with-the-simulator
---

# Create a policy

A policy is owned by the level you create it at, and written for it: every resource starts with `${scope}`, the level's name. The builder offers only what you may grant there, so a policy you build is one IAM accepts. A policy does nothing until you attach it to someone.

## Web UI

### Open Policies

Open **Roles & permissions** at the level (Workspace settings, Organization Settings or Platform Settings), then **Policies**. The table shows each policy's **Name**, **Id**, **Owner**, **Statements** and **Revision**, with each sub-policy below its parent. A policy owned elsewhere opens read-only, with a link to its owner's page.

### Start a new policy

Choose **New policy**. Fill in **Name** and **Description**.

- **Sub-policy of** makes it a sub-policy of a policy listed here. Pick the workspace's access policy, "&lt;workspace&gt; access", for a policy meant for the workspace's people: it then never grants more than the workspace offers, and narrowing the parent narrows it. Leave **No parent** for a policy of its own.
- **Start from** copies a built-in role you may see as a starting point. **Nothing** empties it again.

### Choose in the builder

The **Builder** view lists, by publisher, what you may grant at this level: **Engine** (the kernel services and IAM), **naas_abi** (Nexus: organizations, workspaces, members, features…), then each module by its key (its agents, apps, workflows, pipelines and its own actions). **Search publishers, resource types and actions** filters the whole builder.

For each resource type you need:

1. Under **Actions**, tick the actions. Each shows its level: list, read, write or admin.
2. Under **Resources**, tick a pattern you may grant, tick existing resources from the list (search it, then **Load more**), or type a wildcard after `${scope}/`. A type that cannot be listed reads "Not listed: write a wildcard."

Each type's choice becomes one Allow statement. With a parent, the builder offers only what the parent allows and you may grant.

### Or write statements, YAML or JSON

**Statements** edits each statement: **Effect** (Allow or Deny), **Sid (optional)**, **Actions** and **Resources**. It suggests only what you may grant. **YAML / JSON** shows the whole document, in the **Format** you pick:

```yaml title="Forecasting analysts"
version: "2026-10-13"
statements:
  - sid: UseTriage
    effect: Allow
    actions: ["module:UseAgent"]
    resources: ["${scope}/module:agent/harbor.tickets/Triage"]
  - sid: ReadGraphs
    effect: Allow
    actions: ["triple_store:Query", "triple_store:ListGraphs"]
    resources: ["${scope}/triple_store:graph/*"]
```

Nexus checks the document with IAM as you type and lists every error.

### Create it

Choose **Create policy**. IAM refuses a statement you do not hold ("You cannot grant what you do not hold: …"), shown beside the resource type it names, and a statement that names what its parent allows nowhere ("… above it, does not allow …: it would grant nothing").

Then attach it: see [Give someone access](/capabilities/platform/give-someone-access).

### Edit or delete it later

Select the policy to open it. The editor names its parent and its sub-policies, lists where it is attached under **Attached to**, and saves with **Save changes**. If someone changed it since you opened it, **Reload their version**. A policy that still has sub-policies cannot be deleted: delete them, or give them another parent, first.

## CLI

Not applicable. `abi iam` has no policy commands. Use the Web UI.

## Python

Not applicable. The SDK does not write policies. Use the Web UI or the REST API.

## REST API

:::warning Session only
The routes under `/api/iam/admin/` take a signed-in session only. A personal API key (`abi_pk_…`) is refused with 403 on `/api/iam/`, so a script that holds one cannot write policies.
:::

### Check it

```http
POST /api/iam/admin/policies/validate?scope=abi:nexus:organization/<org>/nexus:workspace/<ws>
Content-Type: application/json

{"text": "version: \"2026-10-13\"\nstatements:\n  - effect: Allow\n    actions: [\"module:UseAgent\"]\n    resources: [\"${scope}/module:agent/harbor.tickets/Triage\"]\n"}
```

The answer lists every error IAM finds, and the normalized document.

### Create it

```http
POST /api/iam/admin/policies
Content-Type: application/json

{
  "name": "Forecasting analysts",
  "description": "What analysts use in Forecasting",
  "scope": "abi:nexus:organization/<org>/nexus:workspace/<ws>",
  "parent": "pol_01jexample0000000000000000",
  "document": {
    "version": "2026-10-13",
    "statements": [
      {"effect": "Allow", "actions": ["module:UseAgent"], "resources": ["${scope}/module:agent/harbor.tickets/Triage"]}
    ]
  }
}
```

`scope` is the owner (none for the platform), `parent` the policy it is a sub-policy of, and the document goes in `document` or, as YAML or JSON, in `text`. `GET /api/iam/admin/publishers?scope=&parent=` is what the builder offers: what you may grant there, within the parent.

### Update or delete it

`PUT /api/iam/admin/policies/{id}` takes `expected_revision` and the fields to change (`parent`: an id sets it, `null` removes it, absent keeps it). `DELETE /api/iam/admin/policies/{id}` deletes it; a parent with sub-policies is a 409 naming them.

## Config

Not applicable. Policies live in IAM, not in `config.yaml`.
