---
sidebar_position: 3
title: "Upgrade to the permission system"
question: What happens when an existing install upgrades to the permission system, and what do I do?

---

# Upgrade to the permission system

naas-abi 3.7.0 and naas-abi-core 3.3.0 (2026-11-07) bring ABI's permission
system, with naas-abi-cli 3.3.0, naas-abi-sdk 0.3.0 and a new package,
naas-abi-idp 0.1.0, the built-in identity provider. This page is for an install
made with an earlier 3.x version; from 2.x, follow
[Migrate from 2.x to 3.0](/capabilities/upgrade/migrate-to-3) first. What is new is in the release note,
[ABI 3.7: the permission system](/capabilities/release-notes/abi-3-7-permission-system).

In short: at its first start, Nexus moves everyone's access into IAM, once,
and each person keeps the access they had. Nexus's own login is gone, so
everyone signs in again through an identity provider. Remote modules log in
with service keys and approved permission manifests instead of keys derived
from `NATS_JWT_SECRET`.

:::warning Upgrade to naas-abi 3.7.1 or later
naas-abi 3.7.0 cannot move an install from an earlier version in one start:
people sign in, but Nexus does not move the role data, so members and viewers
see no workspace, and owners no feature or agent. naas-abi 3.7.1 and
naas-abi-core 3.3.1 (2026-11-09) fix it. Upgrade straight to them, or to a later
version.
:::

## What moves at the first start

Nexus moves each of these once, when the API starts at the new version, and
records each move in its `iam_migrations` table, so a later start skips it.
IAM is the only record of access afterwards.

| Before | After the move |
|---|---|
| Organization and workspace memberships, and the `owner_id` of each | A built-in role (`builtin.owner`, `builtin.admin`, `builtin.member`, `builtin.viewer`) attached at the organization or the workspace. An organization's owners and admins also hold their role below it, so they reach its workspaces as before (`iam_roles_v1`). |
| `is_superadmin` on a user, or `users[].is_superadmin` in the config | `builtin.platform_admin`: every action on everything, except sealed resources (such as the engine's signing keys), with no scope. Nexus still shows the flag as Superadmin. |
| The features of each role (`feature_flags.role_baseline`, `organization_overrides`) | A "Features of &lt;role&gt;" policy per workspace, attached to the people who held that role there; one per organization for a role held org-wide (`role_features_v1`, `role_features_retired_v1`). |
| Features turned on or off in one workspace (`feature_flags.workspace_overrides`, a workspace's own overrides) | A feature turned off leaves the workspace's access policy; one turned on is kept, in a workspace policy, for the people who held a role there (`workspace_feature_sets_v1`). |
| What each workspace turned on or off: Settings › Agents, Apps and Workflows, and an agent's own switch | Policies, per organization and workspace: "&lt;organization&gt; access", "&lt;workspace&gt; access" below it with a Deny of what the workspace had turned off, "&lt;workspace&gt; modules (its people)" for everyone who held a role there, and "Agents turned off in &lt;workspace&gt;" for the agents it built (`policy_tree_v1`). |
| Resource names of the form `abi:<org>:<workspace>:…` | Paths of containers: Nexus registers each organization and workspace with IAM, and IAM rewrites every stored name, pattern, placement and invitation in one transaction (`container_names_v1`). |
| No access policy or default group | Every organization and workspace gets its access policy and its "&lt;level&gt; members" and "&lt;level&gt; admins" groups, whose members follow the roles (`container_defaults_v1`). |
| A workspace's graphs and its prefixes in object storage, documents, vectors and datasets | Placements of those resources in the workspace, and an Allow statement in a workspace policy for a graph it shared. |
| Workspace secrets, encrypted under `SECRET_KEY` | Re-encrypted under their own key, `NEXUS_SECRETS_KEY` (`secrets_encryption_key`). |
| Sessions, refresh tokens, app links and preview tokens signed with `SECRET_KEY` | Ended. The old login's tables (passwords, magic links, reset tokens, refresh tokens) are dropped. |

### Everyone keeps their access

Every person's organizations, workspaces and roles stay the same, and so does
what each of them may use in each workspace: features, agents, apps and
workflows. That includes members and viewers, who keep the agents and apps
their workspace had turned on.

One thing widens: **the platform admin now reaches what a workspace had turned
off.** No switch outside policies is left to hide it from them.

A few things work differently from then on, and the move's report names them:

- An organization's admins and owners reach a workspace made later only
  through a policy attached there, or org-wide.
- A module installed later is in no access policy until someone adds it.
- Someone given a role later in a workspace uses the agents it had built and
  turned off, unless a policy denies them.
- The "&lt;organization&gt; access" and "&lt;workspace&gt; access" policies of
  an upgraded install are **not** attached to the "&lt;level&gt; admins"
  group, since they hold the features the move kept from roles. Admins and
  owners keep what the move gave them. Attach the access policy to the admins
  group to let them use it and derive policies from it. See
  [Access policies and default groups](/capabilities/platform/roles-and-permissions#access-policies-and-default-groups).

### If a move cannot be exact

A move that cannot keep every decision exactly stops: it is logged, nothing is
recorded, and Nexus refuses every module agent, app, workflow and feature until
a start completes it, so access never widens meanwhile. An API process that is
still refusing reads `iam_migrations` again every minute and stops refusing
once the moves are recorded. Fix what the log names, then restart.

## Everyone signs in again

Nexus has no login of its own any more: no password, magic link or reset.
People sign in at an OpenID Connect provider the engine trusts. A new
configuration uses the built-in one, which mails a 6-digit code. Sessions
signed before the upgrade end, so everyone signs in again, and no password
moves.

An account of the old login keeps its id, roles, groups, keys and data. It
needs to exist at the built-in provider first:

1. Once the provider runs, preview what would be made:

   ```bash
   abi user migrate
   ```

2. Make each account exist at the built-in provider, with the same email:

   ```bash
   abi user migrate --apply
   ```

   Running it again makes nobody twice. Addresses the provider cannot mail
   (placeholder domains) are skipped. The API logs a reminder at each start
   while accounts are not linked.

3. Each person signs in with the code mailed to them. At that first sign-in,
   Nexus links the provider's account to the existing one.

Only the built-in provider links an old account, because it proves the address
by mailing a code. People of an organization whose email domain routes to
another provider sign in as new accounts, unless an administrator links the
two. See [`abi user migrate`](/user-guide/reference/cli#abi-user-migrate) and
[An account from before the upgrade](/capabilities/get-started/sign-in#an-account-from-before-the-upgrade).

## Modules log in with service keys

`NATS_JWT_SECRET`, the module keys derived from it (`ABI_MODULE_KEY`,
`abi module key`), `ABI_SERVICE_TOKEN` and the broker users `abi` and `module`
are gone. The engine signs its tokens with keys IAM holds, and `nats.jwt_secret`
is refused at load.

- **The broker** has two users, `engine` (`NATS_ENGINE_PASSWORD`) and `auth`
  (`NATS_AUTH_PASSWORD`), and asks the engine, through an auth callout, about
  every other connection. The `nats:` block of the config logs in as `engine`
  and declares `auth_callout`. See
  [The `nats:` block](/architecture/real-time-fabric#the-nats-block).
- **Each remote module** is a service account, `module/<project>/<module id>`,
  with a service key of its own, `ABI_SERVICE_KEY`. At start it submits its
  permission manifest and waits until an administrator approves it.
  `abi dev up` makes the keys and approves the manifests itself. Elsewhere:

  ```bash
  abi iam service-account create module/<project>/<module id> --key
  abi iam module approve module/<project>/<module id>
  ```

- **Each module's `naas-abi-sdk`** must be 0.3.0 or later, upgraded with the
  engine: an older SDK breaks behind the auth callout.

See [Run a module with a service key](/capabilities/build/modules/run-with-a-service-key),
[Declare module permissions](/capabilities/build/modules/declare-module-permissions) and
[Approve a module's permissions](/capabilities/build/modules/approve-module-permissions).
The built-in identity provider is such a module too, `module/<project>/idp`.

## Deprecated configuration keys

| Key | What happens now |
|---|---|
| `feature_flags.role_baseline`, `feature_flags.organization_overrides`, `feature_flags.workspace_overrides` | Read once, at the first start, by the moves above. Then they do nothing, and Nexus warns at every start while the config sets them: remove them. |
| `feature_flags.enabled_features` | Kept. It says which features exist in the deployment; policies say who uses them. |
| The old login's settings: `auth_password_enabled`, `auth_signup_enabled`, `magic_link_*`, `otp_*`, `access_token_expire_minutes`, `refresh_token_expire_days`, `log_otp_codes_when_email_unavailable` | Accepted and ignored with a warning. `magic_link_email_app_name` is now `email_app_name`, and `rate_limit_login_attempts` is `rate_limit_attempts`. |
| A user's `store_credentials_in_secrets` | Ignored: no password is made. |
| `secret_key` | Signs and encrypts nothing. Read at start only, to move the workspace secrets to `secrets_encryption_key`. |
| `nats.jwt_secret` | Refused. |
| `NATS_JWT_SECRET`, `NATS_ABI_PASSWORD`, `NATS_MODULE_PASSWORD`, `ABI_MODULE_KEY_*`, `NEXUS_USER_*_PASSWORD` in `.env` | Unused: delete them once the stack runs. |

See [`nexus_config`](/capabilities/get-started/configuration#nexus_config) and
[Secrets the CLI generates](/capabilities/get-started/configuration#secrets-the-cli-generates).

## Checklist

### Before

1. **Back up** Nexus's database, the secret store (`.env` with the `dotenv`
   adapter) and the storage volumes. The moves change Nexus's tables and drop
   the old login's: only a backup undoes them.
2. **Check that the stack can mail.** The built-in provider sends sign-in codes
   through the engine's [email service](/capabilities/get-started/configuration#email).
   A stack that cannot mail lets nobody sign in.
3. **Several API replicas, each with its own secret store?** Set the same
   `NEXUS_SECRETS_KEY` (or `secrets_encryption_key`) on each before upgrading,
   and keep `SECRET_KEY` until each one has started once. Otherwise each replica
   generates its own key and re-encrypts the shared database under it.
4. **Nexus on SQLite?** Start a single API process for the first start: the
   moves lock each other out on PostgreSQL only.

### Upgrade

5. Upgrade `naas-abi` to 3.7.1 and `naas-abi-core` to 3.3.1 or later,
   `naas-abi-cli` to 3.3.0 or later and `naas-abi-proto` to 0.3.0 or later, and
   add `naas-abi-idp`. A project that resolves
   them from the `.abi` submodule moves the submodule and runs `uv sync`.
6. Upgrade each remote module's `naas-abi-sdk` to 0.3.0 or later.
7. Update the config, comparing it with what a new project of this version
   gets:
   - `nats:` logs in as `engine` and has an `auth_callout` block; remove
     `jwt_secret`;
   - add an `identity:` block with the built-in provider
     ([`identity`](/capabilities/get-started/configuration#identity));
   - set `services.iam` ([IAM](/capabilities/get-started/configuration#iam));
     the Docker presets keep its store in PostgreSQL;
   - keep `services.iam.modules.auto_approve` off outside `abi dev`.
8. Write the stack's files again: `abi deploy local --regenerate` for Docker
   (it backs up `.env` first and keeps its values), or `abi deploy dokploy`
   for Dokploy, without `--regenerate`, which would replace the database
   passwords; then copy the new keys of `.env.dokploy` to the Environment tab.
   You get the broker's `nats.conf` with its two users and the callout, the
   `idp` service, and the new secrets. Keep `SECRET_KEY` until the first start
   has moved the workspace secrets.

### First start

9. Start the stack, and read the API's log: each move logs its report, with
   notes on what it spelled out, and anything that failed.
10. Create the built-in provider's key, set it as `IDP_SERVICE_KEY`, approve
    its manifest, and start it: see
    [Deploy with Docker › Sign in](/capabilities/deploy/local-docker#sign-in)
    or [Deploy with Dokploy › Sign in](/capabilities/deploy/dokploy#sign-in).
11. Give each remote module its account, key and approved manifest
    ([above](#modules-log-in-with-service-keys)), then start it.
12. Run `abi user migrate`, read the list, then `abi user migrate --apply`.

### After

13. Tell everyone to sign in again with the code mailed to them.
14. Check that a member, a viewer and an admin you know keep their
    organizations, workspaces and access:
    [View as another person](/capabilities/platform/view-as-another-person)
    shows Nexus as each sees it.
15. Attach each upgraded "&lt;organization&gt; access" and
    "&lt;workspace&gt; access" to its admins group where its admins and owners
    should use and derive from it.
16. Remove the deprecated keys from the config, and the unused ones from `.env`.

## The 3.0 pages

[Migrate from 2.x to 3.0](/capabilities/upgrade/migrate-to-3) and
[Breaking changes in 3.0](/capabilities/upgrade/breaking-changes-3) describe
3.0 as it shipped, with `NATS_JWT_SECRET`, the broker users `abi` and `module`,
and `abi module key`. An install coming from 2.x follows them for NATS, then
this page.
