Members, roles and workspaces

A nima workspace has three roles: owner, admin and member. Owner and admin hold the same permissions. A member can read and work with the pipeline but cannot connect integrations, change workspace settings or manage people. This page covers roles, inviting and removing people, belonging to several workspaces, and deleting a workspace.

Workspace roles: owner, admin, member

Owner and admin have identical permissions (all 24 permissions). A member has 12: read users, read/create/update content, read/create/update workflows, read billing, use AI features, use the local bridge, and read and write comments.

A member who opens the admin panel home (Integrations) is redirected to Settings → General, because connecting tools is an owner and admin action.

What a workspace member cannot do

A member holds 12 of the 24 permissions. The missing ones show up in these places:

• Connecting integrations and changing settings. Connecting a tool, PATCH /organizations/settings and creating signal webhook endpoints need the integrations permission. See Workspace settings.
• Deleting content. A member cannot back the documents:write scope, so a key or OAuth grant a member creates never carries it.
• Reading source documents. A member cannot back sources:read, so get_signal_source is unavailable to their keys.
• Managing roles and keys workspace-wide. Only an owner or admin can list, rotate or revoke every key in the workspace.
• Undoing knowledge-graph changes. Listing the knowledge graph's change journal and undoing an entry (/v1/knowledge-graph/journal) is owner and admin only, because an undo rewrites facts for the whole workspace.

A key never exceeds its owner. nima intersects the key's scopes with the key owner's current role on every request, and drops at creation any scope the creator's role cannot back. If none survive, creation fails with 400. The scope table lists which scopes a member can grant.

Invite people to a workspace

An owner or admin invites a person by email and picks a role, admin or member. Invitations never grant owner.

POST /organizations/{orgId}/invitations takes email and role. nima emails a one-time link; the token is never returned by the API.

The rules:

• Expiry. An invitation is valid for 7 days. Resending a still-valid invitation emails a new link, restarts the 7 days, and makes the old link stop working. An expired invitation cannot be resent or accepted (410). It stays in the pending list, keeps its seat, and blocks a new invitation to the same address (409). To invite the person again, first revoke the expired invitation in Settings → Members (or DELETE /organizations/{orgId}/invitations/{id}), then send a new one.
• Seat cap. The plan's seat cap counts current members plus pending invitations, including expired invitations that have not been revoked. When the total reaches the cap, inviting fails with 403. The seeded Free plan allows 3 seats, Pro 20, Enterprise no cap. Nobody is billed today.
• One pending invitation per email. A second invitation to the same address is a 409, as is inviting someone who is already a member.
• The email must match. The person accepts by signing in with Google and opening the link. If the signed-in email differs from the invited email, acceptance fails with 403. A link that was already used, revoked or replaced by a resend returns 404. An expired link returns 410. Accepting a pending invitation to a workspace you already belong to is a 409.

Invitations are pending until someone accepts or revokes them (accepted, revoked). An invitation past its 7 days still shows as pending. In Settings → Members an owner or admin can resend or revoke a pending invitation. Revoking frees the seat.

Changing roles and removing members

An owner or admin changes a member's role between admin and member, or removes the member, from Settings → Members. The owner is fixed: nobody can demote or remove the owner.

• Change a role. PATCH /organizations/{orgId}/members/{userId}/role with role set to admin or member. Changing the owner's role, or your own, is a 400.
• Remove a member. DELETE /organizations/{orgId}/members/{userId}. Removing the owner is a 400. If the removed person was using this workspace, nima moves them to their oldest remaining workspace.
• No ownership transfer. No route or control moves the owner role to someone else. The error messages mention a transfer, but none exists. To hand a workspace over, ask the nima team.

A role change or removal applies to API keys and MCP tokens on their next request, because they look up the key owner's current role every time. The person's signed-in admin-panel session keeps its old role until its access token refreshes, which takes at most 15 minutes.

Revoke a removed member's keys

A removed member's personal API keys stop working for anything useful, but they are not deleted. The key still authenticates, then resolves to no role in the workspace, so every permission-checked call returns 403 and GET /oauth/userinfo reports orgRole: null. Revoke those keys anyway. An owner or admin sees every key in the workspace under Settings → API keys (GET /v1/api-keys?scope=org) and can revoke any of them. MCP OAuth tokens check membership on every refresh and are revoked when the person is no longer a member.

Belonging to several workspaces

A person can belong to any number of workspaces but can own at most 3. Creating a fourth returns 409 with "You can own at most 3 workspaces". The count includes workspaces in a deletion hold, so a workspace scheduled for deletion still takes one of the three slots until it is purged.

• Create another workspace. Use the top-bar action, which opens onboarding with ?new=1. The person becomes owner of the new workspace.
• Switch workspace. Use the workspace switcher in the top bar. It calls POST /auth/switch-org, which marks one membership active and issues new session tokens for it.
• Keys are pinned to one workspace. A key belongs to the workspace it was created in, fixed at creation. It cannot span workspaces.

Deleting a workspace

Only the owner can delete a workspace. Deletion starts a 7-day hold during which the workspace works normally and the owner can cancel. When the hold ends, an hourly sweep purges it.

1. The owner opens Settings → Account, and under Danger zone chooses Delete workspace. The API call is POST /organizations/{orgId}/deletion with confirmSlug set to the workspace slug exactly. A wrong slug is a 400.
2. nima records a deletion time 7 days ahead and shows a banner in the app. The workspace stays fully usable. Scheduling twice is a 409.
3. To cancel, the owner chooses Cancel deletion or calls DELETE /organizations/{orgId}/deletion. Cancelling when nothing is scheduled is a 409.
4. Once the 7 days pass, the next hourly sweep picks the workspace up, checks it is still due, and deletes it.

An admin gets 403 NOT_ORG_ADMIN on these routes, even though admins hold the same permissions as the owner. A workspace with a live paid subscription (active, trialing or past_due) cannot be scheduled for deletion. That cannot arise today because nobody is billed.

What deleting a workspace removes

The purge deletes the workspace's rows in one transaction: the knowledge graph, code-intel indexes, signals and beacons, specs and documents, OAuth tokens and authorization codes (MCP connections), API keys, trigger and dispatch data, agent operation data, HubSpot data, every integration connection (Slack, GitHub, Jira, Linear and the rest), invitations, and finally the workspace itself. The code index is deleted too. Members are moved to their next workspace.

Remove the apps at Slack and GitHub yourself

Deleting a workspace does not revoke tokens held at other services. The purge makes no call to Slack, GitHub or any other integration to revoke access, so the nima app stays installed there. After the purge, remove the nima app from your Slack workspace and your GitHub organization yourself. Do this before deletion if you want a clean cut. Object storage is also not part of the purge code path, so do not rely on deletion to remove uploaded files.

Related pages on workspace access

• What the admin panel does
• What is on in your workspace
• Scopes and permissions
• Workspace settings API