bluenexus.ai Get API Key

Scopes and Permissions

Scopes control what your application can do with a user's access token. You request scopes during OAuth authorization or when creating a Personal Access Token.

Available Scopes

Scope Description
account Read account information and profile
agents-all Full agent management — create, update, delete, and use agents
agents-use Use existing agents (chat only, no management)
llm-all Access LLM chat completions and model listing
connections Manage connections to external services
universal-mcp-read MCP tool discovery only (tools/list)
universal-mcp-read-write MCP tool discovery and execution (tools/list + tools/call)
user-data Access user data features
providers List and view available connectors
messaging-channels Manage messaging channels (Telegram, WhatsApp, Webchat)
openid OpenID Connect — returns an ID token
profile Access profile information (name, picture)
email Access email address

Scopes by Client Role

Not all scopes are available to all client roles. The scopes your app can request depend on its role:

Scope THIRD_PARTY WHITELABEL_CUSTOMER
account Yes Yes
agents-all No Yes
agents-use Yes Yes
llm-all Yes Yes
connections Yes Yes
universal-mcp-read Yes Yes
universal-mcp-read-write Yes Yes
user-data Yes Yes
providers Yes Yes
messaging-channels Yes Yes
openid Yes Yes
profile Yes Yes
email Yes Yes

Key difference: THIRD_PARTY clients cannot request agents-all. They can use agents (agents-use) but cannot create, update, or delete them.

How Scopes Are Resolved

When your app requests scopes during authorization:

  1. BlueNexus checks which scopes are allowed for your client's role
  2. Unknown or disallowed scopes are silently ignored
  3. The granted scopes are returned in the token response's scope field
  4. The access token only permits operations within its granted scopes

If your client has the THIRD_PARTY role (restrictive), BlueNexus uses intersection mode — only scopes that the restrictive role permits are granted. WHITELABEL_CUSTOMER uses union mode — broader access.

Provider Permissions

In addition to API scopes, users can control per-provider access during authorization. This determines which connected services your app can interact with through MCP.

Provider permission levels:

  • read-write — Full access to the provider (read and write)
  • read — Read-only access
  • disabled — No access to this provider

Setting Provider Permissions

During the OAuth authorize request, use the provider_permissions parameter:

https://app.bluenexus.ai/oauth/authorize?
  ...
  provider_permissions={"google":"read-write","slack":"read","github":"disabled"}

When creating a PAT:

{
  "scopes": ["universal-mcp-read-write"],
  "provider_permissions": {
    "google": "read-write",
    "slack": "read"
  },
  "default_provider_permission": "read"
}

Scope Descriptions (User-Facing)

On the consent screen, scopes are presented in user-friendly terms:

Scope User Sees
universal-mcp-read-write "Access and use your connected services"
agents-use "Chat with AI agents"
llm-all "Use AI language models"
connections "Manage your service connections"
account "View your account information"
openid / profile / email "View your identity information"

Checking Granted Scopes

The token exchange response includes the granted scopes:

{
  "token_type": "Bearer",
  "access_token": "...",
  "scope": "universal-mcp-read-write agents-use llm-all"
}

If a requested scope was denied (due to role restrictions or user choice), it won't appear in the scope field.

Listing All Available Scopes

curl https://api.bluenexus.ai/api/v1/auth-scopes \
  -H "Authorization: Bearer ACCESS_TOKEN"

Returns the complete list of scopes with descriptions.

Agent and Knowledge Base Restrictions

Scopes and provider permissions are not the only authorization layer. A session can also carry restrictions on which agents and knowledge bases it may access, independently of what scopes it holds.

These restrictions are orthogonal to scopes:

  • A token with the agents-use scope but an allowedAgentIds restriction cannot call agents outside that list, even though the scope would normally permit it.
  • A token without an allowedKnowledgeBaseIds restriction but missing the universal-mcp-read-write scope cannot use knowledge base tools regardless of the restriction being absent.

Both layers must permit an operation for it to succeed.

Layer Set via Controls
Scopes scope parameter / scopes field API capability categories
Provider permissions provider_permissions Per-provider read/write/disabled
Agent restrictions agent_ids Which agents the token can call
KB restrictions knowledge_base_ids Which knowledge bases the token can access

Restrictions are set when creating a PAT (POST /v1/auth/pat) or during the OAuth authorize request and carry through token refreshes for the lifetime of the session.

Next Steps