---
question: How does my module check permissions of its own?
kind: task
via_web: na
via_cli: na
via_python: available
via_api: available
via_config: na
ref_python: BaseModule.require_action
ref_api: POST /api/iam/admin/policies
prereq: You need a module whose manifest an administrator can approve. See [Declare module permissions](/capabilities/build/modules/declare-module-permissions).
next:
  - /capabilities/build/modules/approve-module-permissions
  - /capabilities/build/modules/declare-module-permissions
---

# Declare a module's own actions

A module's agents, apps, workflows and pipelines are already grantable one by one. When the module also holds things of its own that people may or may not act on (here, research dossiers and the casefiles that group them), it declares an **action catalog**: its resource types and the actions on them. IAM then decides each action like any other, from people's policies, and the module asks IAM before it acts.

- The catalog lives under the module's own service name: its module id in lower case, every other character an underscore. `my_project.research` is `my_project_research`, so its actions are `my_project_research:ReadDossier` and so on.
- It travels with the module's [permission manifest](/capabilities/build/modules/declare-module-permissions) and is registered when an administrator approves it, as submitted. A changed catalog is a new manifest version, pending until approved.
- No role holds a declared action, workspace owners and admins included: a policy grants it. During a run for a user, the user's policies and the module's approved manifest must both allow it. Approval gives the module every action of its own catalog, so the user's grant is what decides.
- A catalog that names a kernel service, `iam`, `nexus`, `module` or another module's service is refused when the module submits it.

## Web UI

Not applicable. A catalog is part of the module's code, and Nexus shows it on the module's card in Module approvals ("Declares `my_project_research` (version 1), approved as submitted"). Once approved, Roles & permissions › Policies offers its actions under the module's name, like any other type, to whoever may grant them.

## CLI

Not applicable. No command writes a catalog. `abi iam module show` prints the one a module submitted, under `catalog`.

## Python

### Write the catalog

Put `iam_catalog.yaml` beside the module's code (or set `iam_catalog` on the class to the same dict). `service` and `version` may be left out: the SDK fills in the module's service and version 1.

```yaml title="src/research/iam_catalog.yaml"
resource_types:
  - name: dossier
    id: path
    description: "A research dossier."
  - name: casefile
    container: true
    parents: ["nexus:workspace"]
    description: "A casefile of dossiers, inside a workspace."
actions:
  - name: ReadDossier
    level: read
    resource_types: [dossier]
    description: "Read a dossier."
  - name: ShareDossier
    level: write
    resource_types: [dossier]
    description: "Share a dossier outside its workspace."
  - name: OpenCasefile
    level: write
    resource_types: [casefile]
    creates: true
    description: "Open a casefile in a workspace."
  - name: CloseCasefile
    level: admin
    resource_types: [casefile]
    deletes: true
    description: "Close a casefile and drop what IAM holds for it."
```

- **`level`** is `list`, `read`, `write` or `admin`.
- **`id`**: `opaque`, `path` (an id of several parts) or `singleton`.
- **`container: true`** makes a type a container: a step in the names of what is inside it. A container type needs an action marked `creates: true` (registering one) and may mark one `deletes: true`. `parents` limits where it may sit (`<service>:<type>`, `-` for the platform; empty: anywhere).

A module's types are always placed in the container of the call: `placement: platform` is refused.

### Enforce an action

In the code that serves the call:

```python title="src/research/__init__.py"
from naas_abi_sdk.services.errors import NotFound, PermissionDenied


class ABIModule(BaseModule[ResearchConfiguration]):
    async def share(self, dossier: str) -> str:
        try:
            await self.require_action("ShareDossier", "dossier", [dossier])
        except (PermissionDenied, NotFound):
            return f"You may not share {dossier}."
        ...
```

`require_action(action, resource_type, parts)` names the action in the module's own catalog and asks IAM for the caller of the call being served: during an agent run or a job for a user, that user and the module both. IAM names the resource itself, in the container of the call (the workspace the user chats in): `<workspace>/my_project_research:dossier/q3-churn`, for example `abi:nexus:organization/org-1/nexus:workspace/ws-2/my_project_research:dossier/q3-churn`. `container=` names another container. It raises `PermissionDenied`, or `NotFound` for a caller who sees nothing of it or a container IAM does not know.

To read the decision instead of raising, call IAM yourself:

```python
decision, resource = await self.engine.services.iam.authorize_declared(
    "my_project_research:ReadDossier", "dossier", ["q3-churn"]
)
if decision.allowed:
    ...
```

`engine.services.iam` needs no entry in `ModuleDependencies`.

### Register a container

A casefile is registered with IAM, inside the workspace of the call. Do it while serving a call made in a workspace (an agent run or a workflow a user started there): outside one, such as a scheduled job or `on_initialized`, the call has no container and `current_call_context().container` is `None`.

```python
from naas_abi_sdk.call_context import current_call_context

workspace = current_call_context().container
if workspace is None:
    raise ValueError("Open a casefile from a call made in a workspace")
created = await self.engine.services.iam.register_container(
    "my_project_research", "casefile", "c-42", parent=workspace
)
casefile = created["name"]  # <workspace>/my_project_research:casefile/c-42
```

Registering is the type's create action, `OpenCasefile`, on the casefile's name: the module and the user it acts for must both hold it. A casefile's id is unique within its type, it never moves, and registering it again under the same parent changes nothing.

Calls made inside it name what they touch there:

```python
with self.engine.inside(casefile):
    await self.require_action("ReadDossier", "dossier", ["q3-churn"])
    # <workspace>/my_project_research:casefile/c-42/my_project_research:dossier/q3-churn
```

`get_container("my_project_research", "casefile", "c-42")` returns its name (None for an unknown one, or one the caller may do nothing on), and `delete_container(...)` deletes it with `CloseCasefile`: the containers below it and the policies, groups and attachments it owns go with it.

### List your resources for the policy builder

So that an administrator picks existing dossiers rather than typing them, register a lister for the type. It answers as the module, and IAM keeps what the caller may list:

```python
from naas_abi_sdk.listers import Listed, ListerQuery, lister


class ABIModule(BaseModule[ResearchConfiguration]):
    @lister("dossier")
    async def dossiers(self, query: ListerQuery):
        # Each dossier by its full name, as authorize_declared returned it when it was made.
        return [Listed(d.resource, d.id, label=d.title) for d in await self.all_dossiers()]
```

The SDK pages the answer, searches it for `query.text` and keeps what lies in the container asked (`query.container`). A type without a lister is offered as patterns and wildcards. `all_dossiers` stands for your own storage.

## REST API

Who may act on a module's resources is set by policies, written and attached like any other ([Create a policy](/capabilities/platform/create-a-policy), [Give someone access](/capabilities/platform/give-someone-access)). A grant in a workspace reaches the dossiers named in that workspace; a dossier inside a casefile is named in the casefile, so it is granted by a policy at the casefile. Nexus's pages manage the platform, organizations and workspaces; a policy at a module's container is made and attached with these routes, with `scope` set to the container's name. `/api/iam/` takes a Nexus session only, never a personal API key.

### Grant in a workspace

```http
POST /api/iam/admin/policies
```

```json title="Request body"
{
  "name": "Research dossiers",
  "scope": "abi:nexus:organization/org-1/nexus:workspace/ws-2",
  "document": {
    "version": "2026-10-13",
    "statements": [
      {
        "effect": "Allow",
        "actions": ["my_project_research:ReadDossier", "my_project_research:OpenCasefile"],
        "resources": ["${scope}/my_project_research:dossier/*", "${scope}/my_project_research:casefile/*"]
      }
    ]
  }
}
```

`${scope}` is where the policy is attached. Attach it to a person or a group at the workspace:

```http
POST /api/iam/admin/attachments
```

```json title="Request body"
{ "policy_id": "<policy id>", "principal_id": "<their IAM id>", "scope": "abi:nexus:organization/org-1/nexus:workspace/ws-2" }
```

### Grant inside a casefile

The same two calls, with `scope` set to the casefile's name, `abi:nexus:organization/org-1/nexus:workspace/ws-2/my_project_research:casefile/c-42`. In the policy, `${scope}` is the casefile itself and `${scope}/my_project_research:dossier/*` the dossiers in it.

You grant only what you hold: a statement allowing an action you do not hold there is refused with a 403 that names it.

## Config

Not applicable. A catalog is not a `config.yaml` block: it travels with the module's manifest.

## Agents, apps and workflows need no catalog

Every agent, app, workflow and pipeline of a module is already a resource of the `module` catalog, named in the workspace where it is used: `module:agent/<module id>/<name>`, `module:app/...`, `module:workflow/...`, `module:pipeline/...`. A policy grants `module:UseAgent`, `module:OpenApp`, `module:RunWorkflow` or `module:RunPipeline` on them at a workspace, and Nexus checks it before a user reaches the item. Declare a catalog only for what the module holds itself. See [Give access to an agent](/capabilities/build/agents/enable-in-a-workspace).
