---
question: How does my module say what it needs from the engine?
kind: task
via_web: na
via_cli: available
via_python: available
via_api: na
via_config: na
ref_cli: abi iam module show
ref_python: BaseModule.permissions
prereq: You need a module. [Create a module](/capabilities/build/modules/creating-a-module) first.
next:
  - /capabilities/build/modules/approve-module-permissions
  - /capabilities/build/modules/run-with-a-service-key
  - /capabilities/build/modules/declare-module-actions
---

# Declare module permissions

A module runs as its own service account and can do nothing until an administrator approves what it asks for. What it asks for is its **permission manifest**: a policy document (Allow and Deny statements of actions on resources) that the module sends when it starts.

The SDK takes the first of these it finds:

1. `BaseModule.permissions`, a dict on the module class;
2. `permissions.yaml`, beside the module's code (`src/research/permissions.yaml` for the module of `src/research/__init__.py`);
3. a default derived from `ModuleDependencies`.

Most modules keep the default: declaring a service in [Add dependencies](/capabilities/build/modules/add-dependencies) is enough. Write a manifest of your own when the module needs something the default leaves out, such as a bus topic, mail it did not send, or another module's declared actions. A manifest you write **replaces** the default: it does not add to it.

## Web UI

Not applicable. A manifest is part of the module's code. Nexus shows what a module submitted on Module approvals, where an administrator approves it: see [Approve a module's permissions](/capabilities/build/modules/approve-module-permissions?via=web).

## CLI

No command writes a manifest. These read the one your module submitted, so you see exactly what an administrator is asked to approve.

### Start the module

The module submits its manifest when it starts, before it registers in discovery:

```bash
abi dev up -d --service research
```

`abi dev up` approves it at once. Elsewhere it waits, and the module logs the command an administrator runs:

```text
my_project.research waits for the approval of its permission manifest 3f9a0c2e71b4: abi iam module approve module/my_project/my_project.research
```

### List the manifests

```bash
abi iam module list
```

```text
approved	module/my_project/my_project.research	3f9a0c2e71b4	submitted 2026-11-10 09:12 UTC
```

Each line is the status (`pending`, `approved`, `rejected` or `superseded`), the module's account, the first 12 characters of the manifest's SHA-256, and when it was submitted. `--status pending` keeps the ones waiting for review.

### Read it

```bash
abi iam module show module/my_project/my_project.research
```

It prints the latest manifest as JSON, with the module's own catalog under `catalog` when it declares one. `--sha256` with a full hash picks another version.

## Python

### See the default

The scaffold declares `model_registry`, `document` and `triple_store`, a `heartbeat` job and a `digest` workflow. Its default manifest is:

```yaml
version: '2026-10-13'
statements:
- sid: UseDocument
  effect: Allow
  actions: [document:*]
  resources:
  - abi:document:namespace/${module.id}
  - abi:document:collection/${module.id}/*
  - abi:document:document/${module.id}/*
- sid: UseModelRegistry
  effect: Allow
  actions: [model_registry:*]
  resources: [abi:model_registry:*, abi:*/model_registry:*]
- sid: UseTripleStore
  effect: Allow
  actions: [triple_store:*]
  resources:
  - abi:triple_store:graph/*
  - abi:*/triple_store:graph/*
  - abi:triple_store:view/*
  - abi:*/triple_store:view/*
- sid: OwnOntologies
  effect: Allow
  actions: [triple_store:LoadSchema]
  resources: [abi:triple_store:schema/module/${module.id}/*]
- sid: OwnJobs
  effect: Allow
  actions: [discovery:ListJobs, discovery:TriggerJob, discovery:ScheduleJob,
            discovery:ListJobRuns, discovery:GetJobRun, discovery:CancelJobRun]
  resources:
  - abi:discovery:job/${module.project}/${module.id}/digest
  - abi:discovery:job/${module.project}/${module.id}/heartbeat
  - abi:discovery:job_run/${module.project}/${module.id}/*
```

Print your module's own, as it will be sent:

```bash
PYTHONPATH=src uv run python -c "from research import ABIModule; from naas_abi_sdk.permissions import module_manifest; import json; print(json.dumps(module_manifest(ABIModule), indent=2))"
```

What each declared service gives by default:

| Service | Default grant |
|---|---|
| `document` | Everything in the module's own namespace, `${module.id}`. |
| `secret` | The secrets named `<module id>/...`, never every secret. |
| `dataset` | The namespace `default` and the catalog. `dataset:QueryUnchecked` (SQL the query check cannot vouch for) is denied. |
| `triple_store` | Every action on graphs and views, and `LoadSchema` on its own ontologies only. |
| `email` | `email:Send` only. The platform keeps a copy of what it sends, sign-in codes included, so reading kept mail is asked for by name. |
| `source_control` | Every action but `AddCollaborator`, which is denied. |
| `bus` | Nothing. A module that uses the bus names its topics: `bus:*` on `abi:bus:topic/<topic>`. |
| Any other service | Every action of that service. |
| `modules=(...)` | The agents, models and apps of the modules it depends on (never the built-in identity provider's `admin` app), and the runs it starts, for itself and for the user it acts for. |
| Its jobs | Each `@job`, `@workflow`, `Workflow` and `Pipeline` class by name. A job declared in `on_load` is not known in advance: a module that declares one writes its own manifest. |

No default grants an admin action.

### Write `permissions.yaml`

Beside the module's code. This one keeps the scaffold's grants and adds a bus topic:

```yaml title="src/research/permissions.yaml"
version: "2026-10-13"
statements:
  - sid: UseDocument
    effect: Allow
    actions: ["document:*"]
    resources:
      - "abi:document:namespace/${module.id}"
      - "abi:document:collection/${module.id}/*"
      - "abi:document:document/${module.id}/*"
  - sid: UseModelRegistry
    effect: Allow
    actions: ["model_registry:*"]
    resources: ["abi:model_registry:*", "abi:*/model_registry:*"]
  - sid: UseTripleStore
    effect: Allow
    actions: ["triple_store:*"]
    resources:
      - "abi:triple_store:graph/*"
      - "abi:*/triple_store:graph/*"
      - "abi:triple_store:view/*"
      - "abi:*/triple_store:view/*"
  - sid: OwnOntologies
    effect: Allow
    actions: ["triple_store:LoadSchema"]
    resources: ["abi:triple_store:schema/module/${module.id}/*"]
  - sid: OwnJobs
    effect: Allow
    actions: ["discovery:ListJobs", "discovery:TriggerJob", "discovery:ScheduleJob",
              "discovery:ListJobRuns", "discovery:GetJobRun", "discovery:CancelJobRun"]
    resources:
      - "abi:discovery:job/${module.project}/${module.id}/digest"
      - "abi:discovery:job/${module.project}/${module.id}/heartbeat"
      - "abi:discovery:job_run/${module.project}/${module.id}/*"
  - sid: PublishFindings
    effect: Allow
    actions: ["bus:*"]
    resources: ["abi:bus:topic/research.findings"]
```

Add `bus` to `ModuleDependencies(services=...)` too: a service the module did not declare is refused in the module itself, whatever the manifest says. Quote `version`: unquoted, YAML reads it as a date (the SDK turns it back into text). JSON reads too, without PyYAML.

### Or set `permissions` on the class

Start from the default and add to it:

```python title="src/research/__init__.py"
from naas_abi_sdk import BaseModule, ModuleDependencies
from naas_abi_sdk.permissions import default_manifest

DEPENDENCIES = ModuleDependencies(services=("model_registry", "document", "triple_store", "bus"))
DEFAULT = default_manifest(DEPENDENCIES, jobs=["heartbeat", "digest"])


class ABIModule(BaseModule[ResearchConfiguration]):
    dependencies = DEPENDENCIES
    permissions = {
        **DEFAULT,
        "statements": [
            *DEFAULT["statements"],
            {
                "sid": "PublishFindings",
                "effect": "Allow",
                "actions": ["bus:*"],
                "resources": ["abi:bus:topic/research.findings"],
            },
        ],
    }
```

Name each job, in Python as in YAML: the broker gives the module the consumers of the jobs its manifest names, and only those. `default_manifest` without `jobs` names none, and a wildcard (`job/.../*`) lets the module trigger its jobs but host none of them.

## REST API

Not applicable. No route writes a manifest: the module sends it over NATS when it starts. Nexus reads it with `GET /api/iam/admin/manifests` for an administrator: see [Approve a module's permissions](/capabilities/build/modules/approve-module-permissions?via=api).

## Config

Not applicable. A manifest is not a `config.yaml` block: it travels with the module's code. `services.iam.modules.auto_approve`, which `abi dev up` sets, decides only whether it waits for review.

## Names in a manifest

- **`${module.id}` and `${module.project}`** are the module's id (`my_project.research`) and its discovery project (`my_project`). They are bound when the manifest is approved, so one manifest serves every project that runs the module.
- **Resources** are written `abi:<service>:<type>/<id>` at the platform. A grant meant for every container (a workspace, a container a module registers) names both forms, `abi:<service>:...` and `abi:*/<service>:...`, as the default grants do.
- **Deny wins** over any Allow, in the same policy too: a module that needs an action the default denies writes its own manifest without that Deny.

## When the manifest changes

The manifest is hashed (its SHA-256, with the module's catalog). When a module starts with a different one:

- the new version is **pending** until an administrator approves it;
- the **previous approved version stays in force**: the module starts on it and logs `my_project.research runs on its approved permissions; a new manifest <sha> waits for approval (abi iam module approve ...)`;
- once the new one is approved, it applies without a restart: the services check the new policy at once, and the broker within the two minutes the module takes to renew its connection.

A module that has never been approved waits: it submits again every five seconds, does not register in discovery, and every call but IAM's is refused. A rejected manifest stops the start with the reason the administrator gave. A version that was replaced and is submitted again (a rollback) is pending again.

## Who uses what the module offers

The manifest is what the **module** may do. Who may use the module's agents, apps, workflows and pipelines is decided per workspace, by policies that grant `module:UseAgent`, `module:OpenApp`, `module:RunWorkflow` or `module:RunPipeline`: no role holds them, workspace owners and admins included. See [Give access to an agent](/capabilities/build/agents/enable-in-a-workspace). During a run for a user, both the user's policies and the module's manifest must allow each call.
