bluenexus.ai Get API Key

Authentication and Authorization

How BlueNexus authenticates users, authorizes apps, and controls access.

Authentication Methods

OAuth 2.1 with PKCE

The primary auth method for third-party apps. BlueNexus implements OAuth 2.1 with mandatory PKCE (S256 only — PLAIN is not allowed).

Grant types supported:

  • authorization_code — For user authorization
  • refresh_token — For token refresh

Key endpoints:

  • GET /v1/auth/authorize — Authorization (redirects to consent screen at app.bluenexus.ai)
  • POST /v1/auth/token — Token exchange and refresh
  • POST /v1/auth/revoke — Token revocation
  • POST /v1/auth/register — Dynamic Client Registration (RFC 7591)

Personal Access Tokens

Long-lived tokens for testing and server-to-server access. Created via POST /v1/auth/pat or the dashboard. See Personal Access Tokens.

SIWE (Sign-In with Ethereum)

Wallet-based authentication for Web3 users. POST /v1/auth/authenticate accepts a signed EIP-4361 message. This is primarily used for direct BlueNexus account creation, not for third-party app auth.

Token Format

  • Algorithm: RS256 (RSA + SHA-256)
  • Format: JWT (JSON Web Token)
  • Verification: Public keys available at /.well-known/jwks.json
  • Claims: Account ID, session ID, scopes, expiry

Authorization — Client Roles

Your app's auth client has a role that determines its capabilities:

Role How Created Agent Management White-Label
THIRD_PARTY DCR or manual Use only (agents-use) No
WHITELABEL_CUSTOMER Manual only Full (agents-all) Yes

All DCR-registered clients get THIRD_PARTY. To get WHITELABEL_CUSTOMER, register manually via the dashboard or API.

Authorization — Scopes

Each access token carries a set of scopes that define what it can do:

Scope Controls
universal-mcp-read MCP tool discovery
universal-mcp-read-write MCP tool execution
llm-all LLM chat completions
agents-all Agent CRUD (WHITELABEL only)
agents-use Agent chat
connections Connection management
account Account info
user-data User data access
providers Provider listing
openid / profile / email OIDC identity

Scope requests are filtered by client role. Unknown scopes are silently ignored.

Authorization — Provider Permissions

Beyond API scopes, each session can have per-provider permissions:

  • read-write — Full access to the provider
  • read — Read-only access
  • disabled — No access

These are set during authorization (via provider_permissions parameter) or PAT creation.

Authorization — Agent and Knowledge Base Restrictions

Sessions can also be restricted to a specific subset of agents and knowledge bases. These restrictions are a separate, orthogonal layer from scopes and provider permissions.

  • allowedAgentIds (string[] | null) — When set, the token is blocked from calling /v1/agents/* for any agent not in the list. null means unrestricted.
  • allowedKnowledgeBaseIds (string[] | null) — When set, knowledge-base MCP tools (read and write) are blocked for KBs outside the list. null means unrestricted.

All four authorization dimensions must permit an operation for it to succeed:

Dimension Controls
Client role Which scopes are requestable
Scopes API capability categories (e.g. agents-use, universal-mcp-read-write)
Provider permissions Per-provider read/write/disabled access
Agent / KB restrictions Which specific agents and knowledge bases the token can reach

Restrictions are set via agent_ids / knowledge_base_ids on the authorize URL or PAT creation body and carry through token refreshes for the lifetime of the session.

Dynamic Client Registration (RFC 7591)

MCP clients auto-register without a pre-existing BlueNexus account:

POST /v1/auth/register
  • Rate limit: 5 requests per minute per IP
  • Always assigns: THIRD_PARTY role
  • Unknown scopes: Silently ignored
  • Redirect URIs: HTTPS required (HTTP allowed for localhost only)

Well-Known Discovery Endpoints

Standard OAuth/OIDC discovery:

Endpoint Standard Purpose
/.well-known/oauth-authorization-server RFC 8414 OAuth server metadata
/.well-known/oauth-protected-resource RFC 8707 Protected resource metadata
/.well-known/openid-configuration OIDC OpenID Connect discovery
/.well-known/jwks.json RFC 7517 Public keys for token verification
/.well-known/oauth-client — Client metadata document

These enable MCP clients to auto-discover the entire auth flow without hard-coded configuration.

Security Properties

  • PKCE mandatory — S256 only, prevents authorization code interception
  • Refresh token rotation — Single-use, rotated on each exchange
  • Session binding — Tokens are bound to sessions; revoking a session invalidates all its tokens
  • Authorization code hashing — Codes are hashed before database storage
  • Client secret encryption — bcrypt hashing + AES-256-GCM encryption
  • Replay detection — Reuse of authorization codes or refresh tokens is detected and logged

Next Steps