Authentication API

OAuth 2.1 endpoints for user authentication and token management.

Base URL: https://api.bluenexus.ai/api/v1/auth

Interactive API documentation is available at api.bluenexus.ai/api/docs (Swagger UI).

POST /auth/register

Dynamic Client Registration (RFC 7591). Register an OAuth client programmatically.

Auth: None required Rate limit: 5 requests/minute per IP

Request:

{
  "client_name": "My App",
  "redirect_uris": ["https://myapp.com/callback"],
  "grant_types": ["authorization_code", "refresh_token"],
  "response_types": ["code"],
  "token_endpoint_auth_method": "none",
  "scope": "universal-mcp-read-write",
  "client_uri": "https://myapp.com",
  "logo_uri": "https://myapp.com/logo.png"
}

Response (201):

{
  "client_id": "client_a1b2c3d4e5f6a1b2c3d4e5f6",
  "client_name": "My App",
  "redirect_uris": ["https://myapp.com/callback"],
  "grant_types": ["authorization_code", "refresh_token"],
  "token_endpoint_auth_method": "none",
  "scope": "universal-mcp-read-write"
}

Confidential clients also receive client_secret and client_secret_expires_at.

---

GET /auth/validate

Preview what the OAuth consent screen will show. Useful for testing.

Auth: None required

Query Parameters:

Parameter	Required	Description
response_type	Yes	Must be code
client_id	Yes	Your client ID
redirect_uri	Yes	Must match registered URI
scope	No	Space-separated scopes
code_challenge	Yes	PKCE code challenge
code_challenge_method	Yes	Must be S256
agent_ids	No	URL-encoded JSON string array of agent IDs. Omit or null for all agents
knowledge_base_ids	No	URL-encoded JSON string array of KB IDs. Omit or null for all KBs

Response (200): Returns client info, requested scopes, and available providers. When agent_ids is present and the user is authenticated, the response includes an agents array (Array<{ id, name, avatar? }>). When MCP scopes are requested and the user is authenticated, the response includes a knowledgeBases array (Array<{ id, name, isDefault }>).

---

GET /auth/authorize

Generate an authorization code. The user must be authenticated.

Auth: User session required

Query Parameters: Same as /auth/validate plus:

Parameter	Required	Description
state	Recommended	CSRF protection token
nonce	No	OIDC replay protection
provider_permissions	No	JSON per-provider permissions
agent_ids	No	URL-encoded JSON string array of agent IDs the session may access. Omit or null for all agents. Example: %5B%22agent_id_1%22%5D
knowledge_base_ids	No	URL-encoded JSON string array of KB IDs the session may access. Omit or null for all KBs

Response: Redirects to redirect_uri?code=AUTH_CODE&state=STATE

---

POST /auth/token

Exchange authorization code or refresh token for access tokens.

Auth: Client credentials (Basic auth or body) for confidential clients Rate limit: 10 requests/minute

Authorization Code Grant

POST /auth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&
code=AUTH_CODE&
redirect_uri=https://myapp.com/callback&
code_verifier=PKCE_VERIFIER&
client_id=CLIENT_ID

Refresh Token Grant

POST /auth/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&
refresh_token=REFRESH_TOKEN&
client_id=CLIENT_ID

Response (200):

{
  "token_type": "Bearer",
  "access_token": "eyJ...",
  "expires_in": 900,
  "refresh_token": "eyJ...",
  "refresh_expires_in": 604800,
  "scope": "universal-mcp-read-write",
  "id_token": "eyJ..."
}

---

POST /auth/revoke

Revoke an access or refresh token.

Auth: Client credentials for confidential clients Rate limit: 10 requests/minute

POST /auth/revoke
Content-Type: application/x-www-form-urlencoded

token=TOKEN_TO_REVOKE&
client_id=CLIENT_ID

Response: 200 OK (always succeeds, even if token is already invalid)

---

GET /auth/userinfo

OpenID Connect UserInfo endpoint. Returns identity claims.

Auth: Bearer token with openid scope

Response (200):

{
  "sub": "account-id",
  "name": "John Doe",
  "email": "john@example.com",
  "picture": "https://..."
}

---

POST /auth/pat

Create a Personal Access Token.

Auth: Bearer token (from a regular session, not a PAT)

{
  "name": "CI/CD Token",
  "scopes": ["universal-mcp-read-write", "llm-all"],
  "expires_in": 2592000,
  "provider_permissions": {
    "google": "read-write",
    "slack": "read"
  },
  "default_provider_permission": "read",
  "agent_ids": ["agent_id_1"],
  "knowledge_base_ids": ["kb_id_1"]
}

Field	Type	Required	Description
name	string	Yes	Descriptive name for the token
scopes	string[]	Yes	Scopes the token can access
expires_in	number	No	Expiration in seconds. Omit for no expiration
provider_permissions	object	No	Per-provider access control
default_provider_permission	string	No	Default permission for unlisted providers
agent_ids	string[]	No	Agent IDs the token may access. Omit or null for all agents
knowledge_base_ids	string[]	No	KB IDs the token may access. Omit or null for all KBs

Response (201):

{
  "name": "CI/CD Token",
  "personal_access_token": "eyJ...",
  "session_id": "session-id",
  "expires_in": 2592000
}

The resulting auth session exposes the restrictions as allowedAgentIds and allowedKnowledgeBaseIds (string[] | null; null means unrestricted). Restrictions persist through token refresh — they are stored on the session, not the token.

---

GET /auth-scopes

List all available authorization scopes.

Auth: Bearer token

Response (200): Array of scope definitions with names and descriptions.