Operator management

Soul Stack operators are Archons: people and machine identities that manage the cluster through the Operator API (REST/HTTP, MCP, web UI). This section is an operational reference for how their identity, permissions, and visibility work. It complements the security model in the Security section: there — how operators prove who they are; here — what they’re allowed to do and what they see.

Archon and AID

Every operator is a record in the operators registry in PostgreSQL. The operator’s identifier is the AID (Archon ID): a stable string under which it appears in the audit log and in role bindings.

• The AID is an arbitrary string from a restricted, safe character set: ^[a-z0-9][a-z0-9._@-]{1,127}$ (starts with a letter or digit; then lowercase ASCII letters, digits, and . _ @ -; length 2–128). Valid examples: archon-alice, alice@corp.com, uid-4815, ops-team.
• The character set is chosen so an AID is safe to embed in filenames, JWT claims, logs, and SQL: no / or \ (path traversal), lowercase ASCII only (no unicode look-alikes or case ambiguity), no control characters or quotes.
• This lets an AID hold an external identity name directly (for example alice@corp.com or uid-4815) without an artificial wrapper.

More on the Archon lifecycle — Archons.

Authentication — JWT

An operator presents the Operator API a signed JWT:

• the Authorization: Bearer <jwt> header on every HTTP/MCP call;
• the signing key lives in Vault (on the Keeper side); the token itself unlocks nothing without signature verification;
• from the sub claim Keeper extracts the AID and then checks that Archon’s permissions.

Tokens have a limited TTL (auth.jwt.ttl_default). The short lifetime is the basis of the revocation model: revoking an Archon means no new tokens will be issued to it, and the active one stops working once the TTL elapses. On top of that, revocation propagates across the cluster through the same mechanism as role changes — a revoked operator stops passing the check almost immediately.

Roles and permissions

An operator’s permissions are set not on the operator directly but through roles. A role is a named set of permissions (specific allowed actions) plus an optional scope selector. An operator gains permissions by being bound to one or more roles.

• A permission is either * (full access, equivalent to the cluster-admin role) or a string of the form <resource>.<action> (incarnation.create, soul.list, role.grant-operator) with an optional filter by covens, hosts, services, and so on.
• An operator can have several roles; permissions add up (OR): an action is allowed if at least one role covers it.
• The full list of available permissions is a dynamic backend catalog, not a table hard-coded into the docs. The web UI and tools pull it from the API. The mechanics of roles and bindings — Roles and access.

Default-deny

The base authorization policy is deny by default, no exceptions: any action not covered by an explicit allow permission is forbidden. There is no “everything open except the listed” — the model is built out of grants only.

Two invariants follow from this, both important for safe operations:

• You can’t grant a permission broader than your own (least-privilege). When creating or granting roles, an operator can’t include a permission it doesn’t hold itself. Otherwise the “manage roles” permission would convert into any permission at all.
• You can’t leave the cluster without an administrator (self-lockout protection). An operation that would strip the last active operator with full access (*) is rejected with a 409 would-lock-out-cluster error.

Both invariants apply to direct role bindings and to bindings via groups (Synod).

Where to start

• Archons — bootstrapping the first operator, creating the rest, revocation, and the last-administrator invariant.
• Roles and access — how roles and permissions work, binding an operator to a role, the dynamic permissions catalog.
• Synod and Purview — operator groups (Synod) and scoped souls visibility (Purview).

How operators prove their identity (JWT, the signing key in Vault) — the Security → Identity section.