---
question: How does a module log in to the engine outside abi dev up?
kind: task
via_web: available
via_cli: available
via_python: available
via_api: available
via_config: available
ref_web: Roles & permissions › Service accounts
ref_cli: abi iam service-account create
ref_python: run_module
ref_api: POST /api/iam/admin/service-accounts/{account_id}/keys
ref_config: dev.modules
prereq: You need a module and an engine with a broker. [Create a module](/capabilities/build/modules/creating-a-module) first.
next:
  - /capabilities/build/modules/approve-module-permissions
  - /capabilities/build/modules/declare-module-permissions
---

# Run a module with a service key

Every module runs as a service account of its own, `module/<project>/<module id>`: `module/my_project/my_project.research` for the module `my_project.research` of the project `my_project`. It proves who it is with a **service key** of that account, `abi_sk_<key id>_<secret>`, which it reads from `ABI_SERVICE_KEY`. The module holds no signing secret and no broker password: with its key it logs in to the broker, and exchanges the key for short-lived tokens (ten minutes at most) that every call carries.

`abi dev up` creates the account and a fresh key for each `dev.modules` entry and approves its manifest. Everywhere else (Docker Compose, a server, Kubernetes, a module in its own repository), you do it:

1. create the account and a key;
2. give the module the key as `ABI_SERVICE_KEY`, and start it;
3. approve the [manifest](/capabilities/build/modules/declare-module-permissions) it submits: see [Approve a module's permissions](/capabilities/build/modules/approve-module-permissions).

A key is shown once: IAM keeps only a hash. An account holds at most five active keys. A module key never expires unless you set an expiry.

## Web UI

Service accounts is a section of Platform Settings › Roles & permissions, for whoever holds `iam:ListPrincipals` at the platform. Accounts for scripts and CI work the same way: see [Manage service accounts](/capabilities/platform/manage-service-accounts).

### Create the account

Open the account menu, then **Platform Settings**, **Roles & permissions** and the **Service accounts** tab. Type the account's name, `module/my_project/my_project.research`, in the field for a new service account and click **Create**. A module's account starts with only what lets it register and submit its manifest.

### Create a key

Open the account's row. Type what the key is for ("prod") and click **Create key**. The key appears once, with **Copy**: copy it now, it cannot be shown again.

### Rotate or revoke

Each active key of the row has **Rotate** (a new key, shown once, and the old one revoked) and **Revoke**.

## CLI

`abi iam` acts as the engine, from the project folder. See [`abi iam service-account`](/user-guide/reference/cli#abi-iam-service-account) and [`abi iam key`](/user-guide/reference/cli#abi-iam-key).

### Create the account and its key

```bash
abi iam service-account create module/my_project/my_project.research --key
```

It prints the account's id and name, then the key on stdout, once (`Shown once: store it now (as ABI_SERVICE_KEY for a module).` on stderr). For a Compose service made by `abi new module`, put it in the project's `.env` as `RESEARCH_SERVICE_KEY`: the service passes it to the module as `ABI_SERVICE_KEY`.

### Start the module

```bash
ABI_NATS_URL=nats://127.0.0.1:4222 \
ABI_SERVICE_KEY=abi_sk_... \
ABI_DISCOVERY_PROJECT=my_project \
python -m research
```

The broker URL carries no login: the module logs in with its key. It submits its manifest and waits for approval, logging the command to run. Approve it with `abi iam module approve module/my_project/my_project.research`.

### Rotate a key

```bash
abi iam key list module/my_project/my_project.research
abi iam key rotate module/my_project/my_project.research <key id>
```

`rotate` prints a new key and revokes the old one. Give the module the new key and restart it.

### Revoke a key

```bash
abi iam key revoke module/my_project/my_project.research <key id>
```

The next exchange and the next broker connection fail. The module renews its connection every two minutes and that renewal fails, so it loses the broker within about two minutes. Tokens already issued expire within ten minutes. `abi iam service-account delete` stops every key of the account at once.

## Python

### Run the module with its key

`python -m research` is the scaffold's `__main__.py`. Its core, for a supervisor of your own:

```python
import asyncio
import os

from naas_abi_sdk import DiscoveryConfiguration, run_module

from research import ABIModule

asyncio.run(
    run_module(
        ABIModule,
        url=os.environ.get("ABI_NATS_URL", "nats://127.0.0.1:4222"),
        token=os.environ["ABI_SERVICE_KEY"],
        configuration=ABIModule.Configuration(),
        discovery=DiscoveryConfiguration(project="my_project"),
    )
)
```

`run_module` submits the manifest and waits for approval before anything else. The module id must be the one in the key's account name, or the start fails: `This module is '...', but its service key belongs to module/...: run it with that module's key`. The scaffold's `__main__.py` refuses to start without a key that starts with `abi_sk_`.

## REST API

These are the calls the Service accounts tab makes. `/api/iam/` takes a Nexus session only, never a personal API key; from a script, use the CLI.

### Create the account

```http
POST /api/iam/admin/service-accounts
```

```json title="Request body"
{ "name": "module/my_project/my_project.research" }
```

The answer is the account, with its `id` (`sa_...`).

### Create a key

```http
POST /api/iam/admin/service-accounts/{account_id}/keys
```

```json title="Request body"
{ "description": "prod" }
```

The answer carries the key's `value` once, with `Cache-Control: no-store`. `expires_in_days` sets an expiry.

### Rotate or revoke

```http
POST /api/iam/admin/service-accounts/{account_id}/keys/{key_id}/rotate
DELETE /api/iam/admin/service-accounts/{account_id}/keys/{key_id}
```

## Config

### Let `abi dev up` make the key

```yaml title="config.yaml"
dev:
  modules:
    - name: research
      module: research
      module_id: my_project.research
```

`abi new module` writes this entry. At each start, `abi dev up` creates the account `module/<project>/<module_id>` if needed, revokes the keys it made before and puts a fresh one in the module's environment, with `ABI_NATS_URL` and `ABI_DISCOVERY_PROJECT`. It also approves every manifest (`services.iam.modules.auto_approve: true` in the overlay it generates). The module never gets the CLI's `NATS_*` variables, IAM's secrets or another module's key. Keep `module_id`: without it the account uses the entry's `name`, `module/my_project/research`, while the module's id is `my_project.research`, and the module stops with "This module is 'my_project.research', but its service key belongs to module/my_project/research: run it with that module's key".

## What the broker lets a module do

The broker asks the engine about every module connection and gives it the subjects its approved manifest allows, computed again each time the module renews its connection, every two minutes. Services check every call at once; the broker follows a changed policy at the next renewal. Should a renewal not happen, the broker's permissions still end with the connection's life (five minutes, ten at most).

- **Always**: IAM's read-only and self-service calls (its token, its manifest, authorization questions, its own containers), the engine's broker control, and replies on its own inbox, which only its key's connections can read.
- **Hosting**: requests to its own agents, apps and jobs, and the completion notices of its own jobs' runs.
- **Each action its manifest allows**: that service's subjects. Agents, models, apps and jobs of other modules: the hosting subjects of the modules its manifest names. Bus topics and events: as granted.
- **Never**: creating a stream or a consumer, writing the jobs stream, the engine's own subjects, `$SYS` and the JetStream API. The engine creates what a module needs, on its behalf.

Before approval a module can call IAM and nothing else, and it is not in discovery.

## Acting for a user

When a user chats with a module's agent or starts its workflow, the module receives a delegation for that user, never their credentials. Calls it makes during that run carry the delegation: the user's policies and the module's manifest must both allow each one. The module renews the delegation through its key, for up to eight hours of run.
