# Delegated admin

Give a person admin rights over chosen areas of Straza, such as the audit chain or sessions, without the root role.

- Who: Root admin
- Where: strazad config file, then console or strazactl

In short: The map `admin.roleAreas` in the server's config file gives a Straza role a slice of the admin plane, such as `audit:read`. Whoever holds that role, assigned by your IGA or an admin, administers those areas and no others. The server checks the area on every request, and only a person, never an AI agent, uses the admin API.


You give a person admin rights over one area of Straza, such as reading the audit chain or revoking sessions, as the root admin. You edit the server's config file, then assign the role in the console or with strazactl. At the end the person administers that area and no other, and the root role `straza-admin` stays the one spelling of full power.

A map in the server configuration, `admin.roleAreas`, says which slice of the admin plane a role administers. Your identity manager decides who holds the role, the same way it decides every other membership.

To let people administer one MCP server and nothing else, give them that server's admin role instead, as [Delegate one MCP server](https://docs.straza.ai/guides/operate/delegate-one-server/index.md) describes. The two compose: a person may hold a mapped role and a server's admin role at once, and the server unions everything they hold.

## Pick the areas

A scope is an area and a verb, written `area:read` or `area:write`, and the verb follows the HTTP method of the request: a GET is a read and everything else is a write. The twelve areas are the same ones that admin API tokens use, so a scope list reads the same wherever you meet it. Every admin route belongs to exactly one area, and a route that no area covers is refused, never let through.

| Area | What it covers |
|---|---|
| `identity` | users, roles, assignments, devices, locks and knowledge packs |
| `sessions` | listing sessions and revoking them, one or all, which is the kill switch |
| `transcripts` | recorded conversation content, kept apart from every other area on purpose |
| `audit` | the decision and admin event history, which holds each tool's input and no conversation text |
| `policy` | PolicySets: read, write, validate, simulate and activate, and the list of tools that were denied because no rule covers them |
| `apps` | MCP servers, access rows, secrets, health and the tool catalog |
| `drafts` | drafts of changes to MCP servers, roles, access rows and policy sets: `drafts:read` lists and reads them, and `drafts:write` checks, creates, changes, reverts, discards and publishes them, where a publish also needs a person with standing over every object in the draft, as [Who may draft and publish](https://docs.straza.ai/guides/changes/who-may-draft/index.md) explains |
| `approvals` | pending approval requests, approval channels and enrolled approver phones |
| `config` | posture reads, the overview, sinks and their replay, the attestation hash registry |
| `changes` | the change feed a pull connector reads |
| `scim` | the SCIM plane at `/scim/v2`, where an identity manager writes users and role membership; `scim:read` opens the reads and the discovery documents, `scim:write` the writes |
| `tokens` | admin API tokens, included in no other scope |

Three scopes deserve a second look before you hand them out:

- `tokens:write` mints admin credentials, and a holder can mint a token with full scope. It is equal to root, and the server logs a warning at boot for every role that receives it.
- `sessions:write` revokes sessions, which stops agents mid-work.
- `scim:write` writes role membership, `straza-admin` included, so it sits at the same tier as `identity:write`.

The word `full` is not a scope you can write in this map. An entry for `straza-admin`, `straza-global-mcp-admin` or `straza-draft-config` refuses to boot, because each would blur a meaning the product fixes.

## Map the role

The map goes in `straza.yaml` on the server. It has no environment variable, because a map does not fit one, so on both profiles you edit the file. The enterprise demo stack ships this entry, which gives anyone holding the role `auditor` a read-only slice of the server:

```yaml
admin:
  roleAreas:
    auditor: [audit:read, sessions:read, transcripts:read]
```

Restart strazad after the edit. The server validates every entry when it starts and refuses to run on a bad one, naming the role and the scope in the error, so a typo cannot leave a delegation silently inert. In the Helm chart the file is the `configYaml` value, rendered into a ConfigMap, and a change to it rolls the pods for you.

## Give someone the role

The role itself is an ordinary role. You create it with `strazactl roles create <name> --kind straza`, and your identity manager then sees it as a SCIM group and writes its membership, where each membership write is an assignment. The console does not make this kind of role, and its New role page says `Straza roles are not made here.` The demo stack's seeder creates `auditor` as a Straza role, the control plane kind, which opens the console and never any agent tool. Assign it to a person as the root admin.

In the console:

Click path in the console: "Roles" › "auditor" › "Assign to a user"

![The Assign release-approvers dialog on the role's page, with lena picked](https://docs.straza.ai/shots/role-assign-user-dark.png)

The same dialog on the approver role release-approvers, with lena picked under User and the button Assign role.

Pick omar under **User** and press **Assign role**. The role's **Areas** tab shows what it opens: `audit`, `sessions` and `transcripts` at `read`, and every other area at `none`, under the line `Set in strazad's config (admin.roleAreas). The console reads it and cannot change it.`

With the CLI:

Terminal, administration, as the root admin:

```sh
strazactl assign auditor --user omar
```

```text
assigned auditor to omar
```

Run the same command a second time and the answer is `strazactl: assignment already exists`, which is how you learn that a role is already held.

Omar is a person the identity manager wrote into Straza, and he holds no other role.

Give the role to people. Only a person uses the admin API, so an AI agent or a service account is refused on every admin route, whatever role it holds. The refusal says that only a person can use the admin API or decide a request, and names the two ways around it: an admin API token that a person mints for automation, and the drafting tools of the built-in straza MCP server, which the role `straza-draft-config` lists.

## Sign in as the holder and probe both sides

The holder signs in the same way as any user, with **Sign in** in the console, which goes through the browser. On every request the server resolves the session's roles, unions their scopes through the map and checks the area of the route. Inside the area everything works as it does for root.

In the console:

Omar signs in at `/console/` with **Sign in**. His sidebar holds **Sessions**, **Audit** and **Transcripts**, the three areas his role reads, and no other.

With the CLI:

strazactl does not carry a person's roles. It runs on an admin API token, whose scope a person fixes when minting it, so omar probes his rights in the console, as its form of this step shows. A token meets the same area check: on a token that holds only `sessions:read`, `strazactl sessions list` answers. `strazactl users list` is refused with `strazactl: token lacks scope identity:read` and exits 1.

If this fails:

`requires role straza-admin, straza-global-mcp-admin or a role mapped in admin.roleAreas. The admin role of a server opens that server's own routes only.`
: None of the person's roles is in the map, so the delegation itself is missing, not one scope of it. Check the map entry, and that the person holds the role.

Every change a delegated admin makes lands on the audit chain under that person's own name, exactly as a root admin's would, so delegation never makes an admin action anonymous.

## What the console shows a delegated admin

The console sign-in page says `Admin roles only. Anyone else lands on the self-service page, still signed in.` After sign-in the sidebar shows only the areas the person's scopes cover, and an address outside them is answered by a locked panel that names what the account does hold and offers a button into the first area it can open. All of that is display only, because the server checks the authority again on every request, so a hand-edited console cannot reach a route that the map does not open.

## Undo it

To take the rights away from one person, delete their assignment of the role, or remove the membership in your identity manager. The next request from that person's session is refused. A membership the identity manager wrote is mastered there, so remove it there as well. That is the same move for an area role and for a server's own role.

In the console:

On the person's sheet, press **Revoke** on the role's row, then confirm.

Click path in the console: "Users" › "omar" › "Revoke" › "Revoke role"

With the CLI:

Terminal, administration, as the root admin:

```sh
strazactl unassign auditor --user omar
```

```text
unassigned auditor from omar
```

To retire an area delegation for everyone, remove the entry from the map and restart. The role then still exists and administers nothing. The kill switch that a `sessions:write` holder operates has its own guide, the [Kill-switch runbook](https://docs.straza.ai/guides/operate/kill-switch-runbook/index.md).


Walked on v1.1.0-117-g106081a8 on 2026-10-06, except the token scope probe, the refusal of AI agents and omar's browser sign-in, written from the code. A throwaway standalone server in an Alpine 3.20 container on Linux, with the map entry added to its config file and the server restarted, and the refused entries checked by booting a second server on each. The admin's strazactl ran on an admin API token minted in the console, so the assign and the unassign ran. In that run omar and mara probed their rights with strazactl after strazactl login from their own home directories, and strazactl no longer signs in, so the probe on a token's own scope was written on 2026-11-01 and not walked. In headless Chromium the console's assign step and the role's Areas tab were clicked as the root admin, and omar's sign-in, sidebar and locked panel were read. The refusal of AI agents on admin routes was checked against the code and not run, because no command hands an agent's session token to another client. In that walk omar's console sign-in used a code, and the browser sign-in that replaced it was written from the code on 2026-10-22 and not walked. Console screenshots show strazad v1.0.0-1753-ga27c516c, standalone.

