Scopes and permissions

Every API key and every OAuth access token carries a list of scopes. A scope is written resource:verb, and it is the only thing that opens an operation to a token. An operation that declares no scope is closed to tokens entirely, however valid the token is. That is why signing in, managing members and minting keys can only be done from a signed-in session.

nima has 17 scopes. Nothing you send can widen a token beyond them.

The 17 nima scopes

The granter column is the workspace permission the person creating the key, or approving the consent screen, must already hold. Owners and admins hold every permission. Members hold a subset, so sources:read, documents:write, integrations:write and, in practice, operations:write are out of their reach.

One built-in first-party client, nima-mcp, may also be granted documents:write, prd:read, prd:write, versions:read and versions:write on the consent screen; a token from it can call those REST routes. No OAuth client can ever be granted a headless scope.

Four scopes are headless scopes: operations:write, integrations:write, actions:approve and identities:write. The MCP transport accepts them, but nima never adds them to OAuth consent or to an existing key.

How to get a key with a headless scope

An owner or admin runs /nima mcp-key operations or /nima mcp-key integrations in Slack (also accepted as an @nima mention or DM), then confirms on the card or tells @nima confirm <code> in the channel within five minutes. Revocation, the key cap and other details are in Authentication.

actions:approve and identities:write are minted by nothing: not the API key route, not the consent screen, not Slack. An API key or OAuth client cannot reach the tools behind them today. Approvals happen on the card in Slack. A signed-in browser session skips scope checks, so it can call those routes directly.

Which scopes the API key form accepts

POST /v1/api-keys validates the scopes array against 13 values: every scope in the table except the four headless ones. Sending operations:write there is a 400 with "error": "Bad Request", not a silent drop.

Routes and tools unlocked by each scope

Paths are relative to https://api.getnima.io. Signals, beacons, knowledge, code, operations and the newer resources sit under /v1. Specs (/documents) and PRDs (/prd) sit at the root with no version segment. There is no other version to ask for. The one exception is spec dispatch, POST /v1/documents/{id}/dispatch, which belongs to agent operations and carries /v1.

Each MCP tool is documented on exactly one MCP tool page; the last column only names it.

Scopes for reading and searching

Scopes for writing signals and specs

Scopes for watches, inbox and scheduled messages

A workspace rule (scope: "org" on POST /v1/watches) needs integrations:write on the same key or token as well as subscriptions:write, plus the integrations-management permission. No key today carries both, so workspace rules can be created only from a signed-in owner or admin session. The workspace must also have watches and outbound dispatch turned on, or the call answers 409; see Watches.

Scopes for agent operations

Reads of operations use documents:read. Controls use operations:write.

Three more tools exist only for a hosted VM run and are never shown to a user token: get_run_brief (GET /v1/operations/{id}/run-brief, documents:read), report_or_ask_pm (POST /v1/agent-runs/{id}/report, signals:write) and wait_for_checks (POST /v1/agent-runs/{id}/wait-for-checks, signals:write).

Scopes for administration and outbound dispatch

Operations that accept more than one scope

GET /oauth/userinfo accepts any of the 17 scopes, so it works with every token. It returns sub, email, isOnboarded, organizationId and orgRole, and no scope list. POST /v1/identities/link accepts integrations:write or identities:write. The MCP transport at POST /mcp accepts the 12 scopes described in Scopes on the MCP server. GET /mcp and DELETE /mcp accept the 8 consent scopes (they answer 405, since the server keeps no stream or session).

Some routes declare a plan feature as well, for example specs under documents, PRDs under prd_generation and code search under code_intelligence. A workspace whose plan lacks the feature can get 403 INSUFFICIENT_PERMISSIONS with details.feature naming it. Handle that response; do not assume a scope alone is enough.

How nima checks scopes

nima checks a token's scopes against the operation on every request, in four steps.

Closed by default. An operation that declares no scope rejects every key and every OAuth token with 403 and the message This endpoint does not accept OAuth access tokens, before the handler runs. A valid key is not enough.

One matching scope is enough. An operation passes a token that holds at least one of the scopes it lists, not all of them. Most operations list exactly one. POST /v1/identities/link (2), POST /mcp (12), GET/DELETE /mcp (8) and GET /oauth/userinfo (all 17) list more.

Scopes only narrow. On every request nima reads the token owner's current role in the workspace the token belongs to and intersects those permissions with the permissions the token's scopes imply. A token can never do more than its owner can do right now. Demote the owner to member and their sources:read key stops fetching sources on the next call. Remove them from the workspace and every token they minted resolves to no role: permission-checked routes answer 403, and GET /oauth/userinfo returns orgRole: null. Access stops without a revocation step, but the keys stay listed and keep authenticating until they are revoked or expire. Tokens never carry super-user rights.

Two different 403 messages. A token missing the scope is refused with OAuth token scopes do not cover this endpoint and details.requiredScopes. A token that holds the scope while its owner has lost the permission is refused with Missing required permissions (AND): … (or (OR) on a route that accepts any one permission), naming the permissions in details.requiredPermissions and the mode in details.mode.

Granting scopes: the silent drop

A scope is grantable only if the person granting it holds all the permissions in the granter column. Scopes they cannot back are dropped from the request and the key is created anyway.

If every requested scope is ungrantable, key creation fails instead with 400 and "None of the requested scopes can be granted by this user", carrying the scopes you asked for in details.requestedScopes.

OAuth consent works the same way and adds one filter in front. A client can only be granted the scopes it registered with. Scopes outside that set are dropped from the request, and only when none are left is the request refused with 400 and "None of the requested scopes are allowed for this client". If the approver's role can back none of what remains, approval fails with 400 and "User lacks permissions to grant the requested scopes". The authorization code is issued for whatever passes both filters.

No route reports a key's or token's scopes back when you present it. What a key carries is in the response you got when you created it and in the key list in Settings → API keys. What an OAuth token carries is in the scope field of the token response.

Scopes only owners and admins can grant

Four scopes are out of a member's reach, for different reasons.

• documents:write needs create, update and delete on content. A member holds create and update but not delete.
• sources:read needs READ_SOURCE_DOCUMENTS. Fetching the document behind a signal replays the request against the source system with the workspace's own integration credential, which reaches further than any one member does.
• integrations:write needs MANAGE_INTEGRATIONS, and it is also minted only through the Slack command above.
• operations:write is backed by permissions a member holds, but the only way to mint it is /nima mcp-key operations in Slack, which accepts owners and admins only.

Scopes on the MCP server

The remote MCP server at https://mcp.getnima.io/mcp offers 8 scopes on its consent screen, and its transport accepts 12.

Consent screen scopes (8). In display order: knowledge:read, signals:read, sources:read, documents:read, signals:write, subscriptions:read, subscriptions:write, inbox:read. Every client that registers dynamically is registered with exactly this set, so a registered MCP client can be granted only these; the headless scopes are never grantable through consent. The screen groups them as read permissions ("Search what nima knows", "Read signals and beacons", "Read the sources behind signals", "Read specs and documents", "See what you are watching", "Read your inbox") and write permissions ("Manage your subscriptions", "File signals for you").

Transport scopes (12). POST /mcp accepts the 8 consent scopes plus the 4 headless scopes. A token holding any one of the 12 opens the endpoint, and each tool then re-checks its own scope.

Visibility rule for tools/list. A signed-in browser session sees every tool. A key or OAuth token sees every tool behind a consent scope, even if the token does not hold that scope, so a stale token learns the tool exists and the failed call triggers re-consent. Tools behind a headless scope appear only when the token holds that scope. VM-only tools never appear. A default OAuth connection therefore lists the 30 consent-scope tools, including the five that read agent operations, and none of the tools that start or control operations, administer the workspace, approve actions or link identities.

The WWW-Authenticate challenge. A 401 carries Bearer error="invalid_token" with the resource metadata URL and the 8 consent scopes. A 403 from a tool behind a consent scope becomes an outer 403 with error="insufficient_scope" and a scope list made of the tool's scope followed by the scopes the token already holds, so re-consent keeps what the client had. That is the client's cue to re-consent:

WWW-Authenticate: Bearer error="insufficient_scope", scope="sources:read knowledge:read signals:read"

A 403 from a tool behind a headless scope is not an outer error. It comes back as a tool result with isError set and this text: "This tool requires an explicit headless grant. Ask a workspace admin to use /nima mcp-key operations or /nima mcp-key integrations in Slack, then connect using that key. Existing OAuth consent does not grant administration." An OAuth client can never administer integrations or compute.

Connect steps live on Connect to nima's MCP server; each tool is documented on its MCP tool page, starting from knowledge tools.

Scope errors

A scope string that is not one of the accepted values is rejected by generic input validation, which answers 400 with "error": "Bad Request" and "message": "Bad Request Exception", without saying which field was wrong. Compare your scope strings against the table above, not against that message.

To see a scope failure, call a route with a key that lacks the scope:

curl -i -H "Authorization: Bearer $NIMA_API_KEY" \
  https://api.getnima.io/v1/signals/3f7a9c21-5b48-4d0e-9a11-6c2f8be41d73/source

A key minted without sources:read gets:

{
  "statusCode": 403,
  "error": "INSUFFICIENT_PERMISSIONS",
  "message": "OAuth token scopes do not cover this endpoint",
  "details": { "requiredScopes": ["sources:read"] },
  "timestamp": "2026-09-22T10:31:07.512Z",
  "path": "/v1/signals/3f7a9c21-5b48-4d0e-9a11-6c2f8be41d73/source"
}

To check that a token is alive without needing a particular scope, call GET /oauth/userinfo. A null orgRole means the owner is no longer a member.