Authentication

Secure your BB-MCP applications with API keys, token management, and best practices. Learn how to authenticate requests and manage access control.

API Key Authentication

BB-MCP uses API key authentication for all requests

Authentication Flow

  1. 1. Obtain API key from your Quiet Stack dashboard
  2. 2. Include API key in Authorization header of all requests
  3. 3. BB-MCP validates the key and returns response or error
# HTTP Request
POST https://api.quietstack.com/v1/contexts
Authorization: Bearer your_api_key_here
Content-Type: application/json

{
  "agent_id": "my-agent",
  "context_data": {
    "task": "classification",
    "result": "positive"
  }
}

Getting Your API Keys

Create and manage API keys in your Quiet Stack dashboard

Step-by-Step Process

1
Sign up for Quiet Stack
Create a free account at quietstack.com
2
Navigate to Dashboard
Go to your user dashboard after login
3
Go to API Keys Section
Click on "API Keys" in the sidebar navigation
4
Create New API Key
Click "Create API Key" and provide a descriptive name
5
Copy and Store Securely
Copy the key immediately - it won't be shown again

Important Security Notice

API keys are only shown once during creation. Store them securely immediately. If you lose a key, you'll need to create a new one and update your applications.

SDK Authentication

Configure authentication in Python and JavaScript SDKs

Python SDK

import bb_mcp
import os

# Method 1: Direct API key
client = bb_mcp.Client(api_key="your_api_key_here")

# Method 2: Environment variable (recommended)
os.environ['BBMCP_API_KEY'] = 'your_api_key_here'
client = bb_mcp.Client()  # Automatically uses env var

# Method 3: From config file
client = bb_mcp.Client.from_config('~/.bbmcp/config.json')

# Test authentication
try:
    status = client.get_status()
    print(f"✅ Authenticated as: {status.user_id}")
except bb_mcp.AuthenticationError:
    print("❌ Authentication failed - check your API key")

JavaScript SDK

import { BBMCPClient } from '@quietstack/bb-mcp';

// Method 1: Direct API key
const client = new BBMCPClient({
  apiKey: 'your_api_key_here'
});

// Method 2: Environment variable (Node.js)
const client = new BBMCPClient({
  apiKey: process.env.BBMCP_API_KEY
});

// Method 3: Custom configuration
const client = new BBMCPClient({
  apiKey: 'your_api_key_here',
  baseURL: 'https://api.quietstack.com/v1',
  timeout: 30000
});

// Test authentication
try {
  const status = await client.getStatus();
  console.log(`✅ Authenticated as: ${status.userId}`);
} catch (error) {
  if (error.name === 'AuthenticationError') {
    console.log('❌ Authentication failed - check your API key');
  }
}

Environment Configuration

Best practices for managing API keys across environments

Environment Variables

# .env file (local development)
BBMCP_API_KEY=sk_dev_1234567890abcdef
BBMCP_BASE_URL=https://api.quietstack.com/v1
BBMCP_TIMEOUT=30000

# Production environment
BBMCP_API_KEY=sk_prod_abcdef1234567890
BBMCP_ENVIRONMENT=production

# Docker
docker run -e BBMCP_API_KEY=sk_dev_123 my-app

# Kubernetes secret
apiVersion: v1
kind: Secret
metadata:
  name: bbmcp-secrets
data:
  api-key: c2tfZGV2XzEyMzQ=  # base64 encoded

Configuration File

# ~/.bbmcp/config.json
{
  "api_key": "your_api_key_here",
  "base_url": "https://api.quietstack.com/v1",
  "timeout": 30000,
  "retry_attempts": 3,
  "environment": "development"
}

# ~/.bbmcp/config.yaml (alternative)
api_key: your_api_key_here
base_url: https://api.quietstack.com/v1
timeout: 30000
retry_attempts: 3
agent_defaults:
  agent_id: my-default-agent
  metadata:
    environment: development

Key Types and Permissions

Different API key types for different use cases

Key TypePrefixPermissionsUse Case
Full Access
Complete access
sk_
✅ Create contexts
✅ Read contexts
✅ Verify contexts
✅ Manage webhooks
Server applications, backend services
Read Only
Query access only
sk_ro_
❌ Create contexts
✅ Read contexts
✅ Verify contexts
❌ Manage webhooks
Analytics, monitoring, audit tools
Public
Client-safe
pk_
❌ Create contexts
✅ Read public contexts
✅ Verify contexts
❌ Manage webhooks
Frontend apps, public verification
Restricted
Limited scope
sk_r_
✅ Create contexts*
✅ Read own contexts
✅ Verify contexts
❌ Manage webhooks
Third-party integrations, specific agents
* Restricted keys can only create contexts for specified agent IDs

Authentication Error Handling

Handle authentication errors gracefully in your applications

Common Authentication Errors

401
Invalid API Key

The API key is malformed, expired, or doesn't exist. Check your key and regenerate if needed.

403
Insufficient Permissions

Your API key doesn't have permission for this operation. Use a key with appropriate permissions.

429
Rate Limited

You've exceeded your rate limit. Implement exponential backoff and retry logic.

Error Handling Code

# Python error handling
import bb_mcp
from bb_mcp.exceptions import AuthenticationError, PermissionError, RateLimitError

def create_context_with_retry(client, context, max_retries=3):
    for attempt in range(max_retries):
        try:
            return client.contexts.create(context)
        except AuthenticationError:
            print("❌ Invalid API key - check your credentials")
            raise  # Don't retry auth errors
        except PermissionError:
            print("❌ Insufficient permissions - check key type")
            raise  # Don't retry permission errors  
        except RateLimitError as e:
            if attempt == max_retries - 1:
                raise
            wait_time = 2 ** attempt  # Exponential backoff
            print(f"Rate limited, waiting {wait_time}s...")
            time.sleep(wait_time)
        except Exception as e:
            print(f"Unexpected error: {e}")
            if attempt == max_retries - 1:
                raise
            time.sleep(1)

Security Best Practices

Protect your API keys and follow security guidelines

✅ Do

  • Store API keys in environment variables
  • Use different keys for different environments
  • Rotate keys regularly (every 90 days)
  • Use least privilege principle (restricted keys)
  • Monitor API key usage in dashboard
  • Implement proper error handling

❌ Don't

  • Hardcode API keys in source code
  • Commit API keys to version control
  • Share API keys via email or chat
  • Use production keys for testing
  • Include keys in client-side code (unless public)
  • Ignore authentication errors

Testing Your Authentication

Verify your API key setup is working correctly

Quick Test with cURL

# Test authentication
curl -X GET https://api.quietstack.com/v1/status \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json"

# Expected response (success)
{
  "status": "authenticated",
  "user_id": "user_123",
  "plan": "starter",
  "rate_limit": {
    "requests_remaining": 999,
    "reset_time": "2024-01-15T11:30:00Z"
  }
}

# Expected response (failure)
{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "The provided API key is invalid or expired"
  }
}