User Management

NimbleBrain supports multi-user environments where each person has their own identity, conversations, and workspace memberships. User management is available with the dev adapter (the built-in local identity store) and with the oidc adapter.

Auth adapters

How users are managed depends on your authentication configuration in instance.json:

Adapter	User management	Description
dev	Organization → Users	"adapter": "dev". Identities live in the built-in local store under users/. No credential is checked and every request is the built-in owner (see Security), but users, roles, and ownership still apply.
oidc	External provider	Users are managed in your OIDC provider. NimbleBrain creates a local record on first login, or binds one an admin created ahead of time. See Signing in with OIDC.
workos	External provider (WorkOS)	Identities and sign-in are managed in WorkOS / AuthKit.

Tip

The dev adapter checks no credential. The dev launchers (bun run dev and its variants) write it for you; everywhere else, instance.json must name an adapter or the server does not start.

Signing in with OIDC

Under the oidc adapter, a user’s account is their provider subject: the token’s iss and sub claims. Each sign-in finds the local record in this order:

1. The record bound to that issuer and subject. A user created at first login is bound when it is created.
2. A record with the token’s email that an admin created ahead of time and no subject is bound to yet. That sign-in binds the record to the subject.
3. Neither: a new record, as Member, bound to the subject.

Because the subject decides, a user whose email changes at the provider keeps the same account. A record bound to one subject is never matched by email: if the provider gives that email to a different person, their sign-in is refused and logged, and no second record is created.

The binding is stored in the identity field of the user’s users/<id>/profile.json and includes the issuer. If you change issuer in instance.json, users bound to the old issuer are refused. To let one sign in through the new issuer, set identity to <new issuer>#<their sub at the new issuer>; their next sign-in matches it.

Managing users

Org admins and owners manage users from Organization → Users (/org/users). The page lists everyone in the organization with their display name, email, org role, and creation date, and flags deactivated users.

• Create user — enter an email and a display name and pick a role (Member or Admin). Under dev and oidc the user is added to the local identity store; under workos the identity is created in WorkOS.
• Deactivate — asks first, then revokes the user’s access at once. You cannot deactivate yourself.
• Restore — re-enables a deactivated user.

The agent cannot manage users. The page calls the nb__manage_users tool, which is app-only: it never appears in the agent’s tool list or in an external MCP client’s tools/list.

nb__manage_users supports these actions:

Action	What it does
create	Create a user (requires email and displayName; optional orgRole, default member)
update	Change a user’s email, displayName, or orgRole
delete	Deactivate a user (soft delete) — revokes sign-in, keeps the record
restore	Re-enable a previously deactivated user
list	List all users

The Users page has no control for update: the web UI cannot change an existing user’s email, display name, or org role, and it creates users only as Member or Admin, never Owner.

Org roles

Every user has one org-level role:

Org role	Can manage users	Description
owner	Yes	Full administrative control. The last active owner cannot be demoted or deactivated.
admin	Yes	Can create, update, and deactivate users.
member	—	Standard user. Chats and uses tools; cannot manage other users.

Note

The last active owner is protected. nb__manage_users refuses to demote or deactivate them until you promote another user to owner first — this prevents locking the org out.

Deactivating users

Deactivating is a soft delete: the user can no longer sign in, but their record stays, so they are listed as deactivated (in the Users page and in workspace member lists) and can be restored with the same ID and memberships. It does not delete the underlying provider identity, which would be irreversible and would orphan their workspace memberships.

Caution

Deactivating a user revokes their access on the next request. Their existing conversations are owned by them and are not deleted, but become inaccessible while they’re deactivated.

Workspace membership

Org roles control who can manage users. Workspace membership controls who can use a given workspace’s apps and tools. A user can belong to multiple workspaces, with a per-workspace role of admin or member.

Manage membership from the workspace’s Settings → Members: add someone in the organization by email, change a role, or remove someone. The agent cannot do this for you; the manage_workspaces tool behind that page is app-only.

Workspace member management requires admin membership in that workspace, or an org role of admin or owner, which can manage the members of any workspace. Workspace roles:

Workspace role	Manage members	Install connectors	Chat & use tools
admin	Yes	Yes	Yes
member	—	—	Yes

Note

Conversations are owned by the individual who created them, not shared across a workspace. There is no way to view all conversations in a workspace.

See Workspaces for more on creating workspaces and assigning members.

Feature flag

User management is controlled by the userManagement feature flag, which defaults to true. To disable:

nimblebrain.json

{
  "features": {
    "userManagement": false
  }
}

When disabled, the nb__manage_users tool is not registered, so the Users page cannot load or change users.

What’s next

• Workspaces — assign users to workspaces with roles
• Connectors — shared services within a workspace