Authentication Guide

This guide covers authentication methods and best practices for the BlueNexus AI platform.

Authentication Methods

API Key Authentication

The simplest way to authenticate with the BlueNexus AI API:

curl -X GET "https://api.bluenexus.ai/api/v1/accounts/me" \
  -H "Authorization: Bearer YOUR_API_KEY"

Creating API Keys

1. Log into your BlueNexus AI dashboard

2. Navigate to Settings → API Keys

3. Click Create New API Key

4. Give your key a descriptive name

5. Select appropriate scopes

6. Copy the generated key (you won't see it again!)

API Key Scopes

• api:read - Read access to API resources

• api:write - Write access to API resources

• api:admin - Administrative access

• connections:read - Read connection data

• connections:write - Manage connections

• data:read - Read data collections

• data:write - Write data collections

• llm:read - Access LLM services

• mcp:read - Access MCP servers

• mcp:write - Manage MCP servers

OAuth 2.0 Authentication

For applications that need to access user data:

Authorization Code Flow

// 1. Redirect user to authorization URL
const authUrl = `https://api.bluenexus.ai/oauth/authorize?` +
  `client_id=${CLIENT_ID}&` +
  `redirect_uri=${REDIRECT_URI}&` +
  `response_type=code&` +
  `scope=api:read api:write&` +
  `state=${STATE}`;

window.location.href = authUrl;

// 2. Handle callback
const urlParams = new URLSearchParams(window.location.search);
const code = urlParams.get('code');
const state = urlParams.get('state');

// 3. Exchange code for tokens
const response = await fetch('https://api.bluenexus.ai/oauth/token', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    grant_type: 'authorization_code',
    code: code,
    redirect_uri: REDIRECT_URI,
    client_id: CLIENT_ID,
    client_secret: CLIENT_SECRET
  })
});

const tokens = await response.json();

Token Refresh

const refreshResponse = await fetch('https://api.bluenexus.ai/oauth/token', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    grant_type: 'refresh_token',
    refresh_token: REFRESH_TOKEN,
    client_id: CLIENT_ID,
    client_secret: CLIENT_SECRET
  })
});

Personal Access Tokens

For long-term API access:

curl -X POST "https://api.bluenexus.ai/api/v1/auth/pta" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My API Token",
    "scopes": ["api:read", "api:write"],
    "expires_in": 86400
  }'

SDK Authentication

Python SDK

import bluenexus

# API Key authentication
client = bluenexus.Client(api_key="YOUR_API_KEY")

# OAuth authentication
client = bluenexus.Client(
    client_id="YOUR_CLIENT_ID",
    client_secret="YOUR_CLIENT_SECRET",
    redirect_uri="https://yourapp.com/callback"
)

JavaScript SDK

import { BlueNexusClient } from '@bluenexus/sdk';

// API Key authentication
const client = new BlueNexusClient({
  apiKey: 'YOUR_API_KEY'
});

// OAuth authentication
const client = new BlueNexusClient({
  clientId: 'YOUR_CLIENT_ID',
  clientSecret: 'YOUR_CLIENT_SECRET',
  redirectUri: 'https://yourapp.com/callback'
});

Go SDK

package main

import (
    "github.com/bluenexus/go-sdk"
)

// API Key authentication
client := bluenexus.NewClient("YOUR_API_KEY")

// OAuth authentication
client := bluenexus.NewOAuthClient(
    "YOUR_CLIENT_ID",
    "YOUR_CLIENT_SECRET",
    "https://yourapp.com/callback",
)

Security Best Practices

API Key Security

1. Never commit API keys to version control

2. Use environment variables for API keys

3. Rotate API keys regularly

4. Use the principle of least privilege

5. Monitor API key usage

# Good: Use environment variables
export BLUENEXUS_API_KEY="your_api_key_here"

# Bad: Hardcode in scripts
api_key="your_api_key_here"

OAuth Security

1. Use HTTPS for all OAuth flows

2. Validate state parameters

3. Store tokens securely

4. Implement token refresh

5. Handle token expiration gracefully

// Validate state parameter
if (state !== expectedState) {
  throw new Error('Invalid state parameter');
}

// Store tokens securely
localStorage.setItem('access_token', tokens.access_token);
localStorage.setItem('refresh_token', tokens.refresh_token);

Token Management

1. Implement automatic token refresh

2. Handle token expiration

3. Store tokens securely

4. Revoke unused tokens

5. Monitor token usage

class TokenManager {
  constructor() {
    this.accessToken = localStorage.getItem('access_token');
    this.refreshToken = localStorage.getItem('refresh_token');
  }

  async getValidToken() {
    if (this.isTokenExpired(this.accessToken)) {
      await this.refreshAccessToken();
    }
    return this.accessToken;
  }

  async refreshAccessToken() {
    const response = await fetch('/oauth/token', {
      method: 'POST',
      body: JSON.stringify({
        grant_type: 'refresh_token',
        refresh_token: this.refreshToken
      })
    });
    
    const tokens = await response.json();
    this.accessToken = tokens.access_token;
    localStorage.setItem('access_token', this.accessToken);
  }
}

Error Handling

Common Authentication Errors

Error Code	Description	Solution
401 Unauthorized	Invalid or missing credentials	Check API key or token
403 Forbidden	Insufficient permissions	Check scopes and permissions
429 Too Many Requests	Rate limit exceeded	Implement backoff strategy
Token Expired	Access token expired	Refresh the token

Error Handling Example

async function makeAuthenticatedRequest(url, options = {}) {
  try {
    const token = await tokenManager.getValidToken();
    
    const response = await fetch(url, {
      ...options,
      headers: {
        ...options.headers,
        'Authorization': `Bearer ${token}`
      }
    });

    if (response.status === 401) {
      // Token expired, try to refresh
      await tokenManager.refreshAccessToken();
      return makeAuthenticatedRequest(url, options);
    }

    if (response.status === 429) {
      // Rate limited, implement backoff
      const retryAfter = response.headers.get('Retry-After');
      await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
      return makeAuthenticatedRequest(url, options);
    }

    return response;
  } catch (error) {
    console.error('Authentication error:', error);
    throw error;
  }
}

Multi-Factor Authentication

Enabling 2FA

1. Log into your BlueNexus AI dashboard

2. Navigate to Settings → Security

3. Click Enable Two-Factor Authentication

4. Scan the QR code with your authenticator app

5. Enter the verification code

6. Save your recovery codes

2FA with API

When 2FA is enabled, some operations require additional verification:

curl -X POST "https://api.bluenexus.ai/api/v1/auth/verify-2fa" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "123456"
  }'

Testing Authentication

Test API Key

Use the test endpoint to verify your authentication:

curl -X GET "https://api.bluenexus.ai/api/v1/auth/validate" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "data": {
    "valid": true,
    "user": {
      "id": "user_123",
      "email": "[email protected]"
    },
    "scopes": ["api:read", "api:write"]
  }
}

Troubleshooting

Common Issues

1. Invalid API Key: Check that your API key is correct and active

2. Expired Token: Refresh your access token

3. Insufficient Scopes: Check that your token has the required scopes

4. Rate Limiting: Implement exponential backoff

5. Network Issues: Check your network connection and firewall settings

Debug Mode

Enable debug mode for detailed error information:

const client = new BlueNexusClient({
  apiKey: 'YOUR_API_KEY',
  debug: true
});

Related Documentation

• Authentication API Reference - Complete API reference

• Security Overview - Security best practices

• OAuth Integration Guide - OAuth implementation

• SDKs Reference - Official SDKs