---
question: How do I approve, narrow or reject what a module asks for?
kind: task
via_web: available
via_cli: available
via_python: na
via_api: available
via_config: available
ref_web: Roles & permissions › Module approvals
ref_cli: abi iam module approve
ref_api: POST /api/iam/admin/manifests/{principal_id}/{sha256}/approve
ref_config: services.iam.modules.auto_approve
next:
  - /capabilities/build/modules/run-with-a-service-key
  - /capabilities/build/modules/declare-module-permissions
---

# Approve a module's permissions

A module that starts on its own service key sends its [permission manifest](/capabilities/build/modules/declare-module-permissions) and waits. Until an administrator approves it, the module does not show in discovery and every call it makes, but IAM's, is refused. Each submitted version is listed with a status: `pending`, `approved`, `rejected` or `superseded`.

You have three answers:

- **Approve** it as submitted.
- **Narrow** it: remove actions or resources from its Allow statements, then approve what is left. Nothing can be added, and every Deny stays as submitted (removing one would widen the grant).
- **Reject** it, with a reason. The module stops at start and logs the reason.

An approved manifest becomes the module's policy, `module.<project>.<module_id>` (`module.my_project.my_project.research`), attached to its account, with `${module.id}` and `${module.project}` bound. The actions the module [declares of its own](/capabilities/build/modules/declare-module-actions) are registered at the same time, as submitted: narrowing applies to the permissions, not to the catalog. The module needs no restart: a waiting module picks up the approval within five seconds and reconnects.

When a module sends a new manifest, the previous approved one stays in force while the new one is pending. Approving or rejecting decides the pending version only.

## Web UI

Module approvals is a section of Platform Settings › [Roles & permissions](/capabilities/platform/roles-and-permissions#where-the-pages-are). It shows to whoever holds `iam:ListManifests` at the platform; Approve and Narrow need `iam:ApproveManifest`, Reject `iam:RejectManifest`.

### Open Module approvals

Open the account menu, then **Platform Settings**. Under Access, open **Roles & permissions**, then the **Module approvals** tab. The **Status** filter starts on `pending`; `approved`, `rejected`, `superseded` and `all` show the others.

### Read the manifest

Each card names the module's account, its status, `<project>/<module id>`, the first 12 characters of the manifest's SHA-256 and when it was submitted. Below are its statements, each Allow or Deny with its **Actions** and **Resources**. A module that declares actions of its own shows them under "Declares `<service>` (version N), approved as submitted".

### Decide

- **Approve** approves the manifest as submitted.
- **Narrow…** turns every action and resource of the Allow statements into a checkbox. Clear the ones the module should not get; Deny statements are marked "(stays as submitted)". The button then reads **Approve narrowed** (or **Approve as submitted** when nothing was cleared). **Cancel** goes back.
- **Reject…** asks for a reason ("Why it is rejected (the module's owner reads this)"); **Reject manifest** sends it.

You approve no more than you hold: a statement granting something you do not hold is refused with IAM's message, which names it. Narrow it out, or ask someone who holds it.

## CLI

`abi iam` acts as the engine, from the project folder, with no sign-in: whoever holds the project's config may approve. See [`abi iam module`](/user-guide/reference/cli#abi-iam-module).

### List what waits

```bash
abi iam module list --status pending
```

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

### Read it

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

It prints the latest submitted version as JSON. `--sha256` with a full hash shows another.

### Approve it

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

```text
approved module/my_project/my_project.research 3f9a0c2e71b4: the module reconnects with its new permissions
```

Without `--sha256` it approves the latest **pending** version. That is not always the one `show` printed: `show` prints the latest submitted version, whatever its status, and a rollback makes an older version pending again beside a newer approved one, or a newer rejected version may sit beside an older pending one. Before you approve, read the pending line of `abi iam module list --status pending`, and check that the 12 characters `approve` prints are the ones that line showed. To read that exact version, or to approve a rejected or superseded one, name it with `--sha256` and its full hash: `list` prints only the first 12 characters, which the command does not accept, so take the full one from the REST API's `sha256`.

### Or narrow it

Save the manifest, remove what the module should not get, and approve the file (YAML or JSON):

```bash
abi iam module show module/my_project/my_project.research > narrowed.json
# edit narrowed.json: drop actions or resources from Allow statements
abi iam module approve module/my_project/my_project.research --document narrowed.json
```

The CLI approves the document as given: unlike Nexus, it does not compare it with what the module submitted. Keep it a narrowing: remove, never add, and keep every Deny.

### Or reject it

```bash
abi iam module reject module/my_project/my_project.research --reason "No access to the bus in this deployment"
```

Each change tells a running engine over the broker, so it drops its IAM cache at once.

## Python

Not applicable. Approving is an administrator's act, not the module's: a module can only submit and wait. Use Nexus, the CLI or the REST API.

## REST API

These are the calls the Module approvals tab makes. `/api/iam/` takes a Nexus session only, never a personal API key (`abi_pk_...`): a key cannot administer permissions. From a script, use the CLI.

### List the manifests

```http
GET /api/iam/admin/manifests?status=pending
```

Each item has `principal_id` (the module's `sa_` account id), `account_name`, `sha256`, `module_id`, `project`, `status`, `document` (its statements), `catalog` (the declared actions, or `null`), `submitted_at`, `decided_at`, `decided_by` and `reason`.

### Approve

```http
POST /api/iam/admin/manifests/{principal_id}/{sha256}/approve
```

With no body it approves the manifest as submitted. To narrow it, send the narrowed policy:

```json title="Request body"
{ "document": { "version": "2026-10-13", "statements": [ ... ] } }
```

Nexus checks that it narrows the submitted one: an Allow may lose actions and resources, none may gain or appear, and the Deny statements stay exactly as submitted. A grant you do not hold answers 403 with IAM's message.

### Reject

```http
POST /api/iam/admin/manifests/{principal_id}/{sha256}/reject
```

```json title="Request body"
{ "reason": "No access to the bus in this deployment" }
```

## Config

### Approve automatically in development

```yaml
services:
  iam:
    modules:
      auto_approve: true
```

Every manifest is then approved as it is submitted. `abi dev up` writes this in the overlay it generates, so modules started by `abi dev up` never wait. Fresh configs and the Docker templates keep `false`: never set it on a deployment that runs modules you have not reviewed. See [IAM](/capabilities/get-started/configuration#iam) in the Configuration Reference.

## What an approval does not grant

- **People's access.** The manifest is what the module may do. Who may use its agents, apps, workflows and pipelines in a workspace is set by policies granting `module:UseAgent`, `module:OpenApp`, `module:RunWorkflow` or `module:RunPipeline` there. See [Give access to an agent](/capabilities/build/agents/enable-in-a-workspace).
- **More than a user holds.** When the module acts for a user, the user's policies and the module's approved manifest must both allow each call.
- **Broker administration.** A module never creates streams or consumers, nor reads the engine's subjects: see [what the broker lets a module do](/capabilities/build/modules/run-with-a-service-key#what-the-broker-lets-a-module-do).
