Authentication

Learn how to authenticate with Browserman's API and MCP services.

API Key Authentication

Browserman uses API keys for authentication. API keys are associated with your account and grant access to the API.

Getting Your API Key

1. Visit app.browserman.run and log in
2. Click on API Keys in the left sidebar navigation
3. Click the + New Key button in the top right
4. Enter a descriptive name for your key:
   • Examples: "Production API", "Development", "CI/CD Pipeline", "My Project"
   • Choose a name that helps you identify where this key is used
5. Click Create Key
6. Important: Copy the key immediately and store it securely
   • The key is only shown once for security reasons
   • If you lose it, you'll need to create a new key
7. The key will appear in your keys list with:
   • Key name
   • Masked key value (e.g., sk_live_xxxx...xxxx)
   • Created date
   • Last used date
   • Status (Active/Revoked)

Keep Your API Key Secure

Your API key grants full access to your Browserman account. Never share it, commit it to version control, or expose it in client-side code.

Using API Keys

Include your API key in the Authorization header of every request:

curl https://api.browserman.run/api/platforms \
  -H "Authorization: Bearer YOUR_API_KEY"

JavaScript:

const response = await fetch('https://api.browserman.run/api/platforms', {
  headers: {
    'Authorization': `Bearer ${API_KEY}`
  }
});

Python:

import requests

response = requests.get(
    'https://api.browserman.run/api/platforms',
    headers={'Authorization': f'Bearer {API_KEY}'}
)

API Key Types

Personal Access Keys

• Created by individual users
• Full access to your accounts and resources
• Can be revoked at any time
• Recommended for development and testing

Service Keys

• Created for specific applications or services
• Can have limited permissions
• Ideal for production deployments
• Easier to rotate without affecting other services

MCP Authentication

For Model Context Protocol (MCP) integration, configure your API key in the MCP client.

Claude Desktop

Edit your config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "browserman": {
      "url": "https://mcp.browserman.run",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Security Best Practices

1. Never Commit API Keys

Bad:

// ❌ Never do this
const API_KEY = 'sk_live_abc123def456';

Good:

// ✅ Use environment variables
const API_KEY = process.env.BROWSERMAN_API_KEY;

2. Use Environment Variables

Node.js:

export BROWSERMAN_API_KEY=sk_live_abc123def456

require('dotenv').config();
const API_KEY = process.env.BROWSERMAN_API_KEY;

Python:

export BROWSERMAN_API_KEY=sk_live_abc123def456

import os
API_KEY = os.environ.get('BROWSERMAN_API_KEY')

3. Rotate Keys Regularly

Set a schedule to rotate API keys:

• Production keys: Every 90 days
• Development keys: Every 180 days
• Immediately if compromised

Rotation process:

1. Generate new API key
2. Update applications with new key
3. Monitor for issues
4. Revoke old key after 24 hours

4. Use Separate Keys for Different Environments

# Development
BROWSERMAN_API_KEY=sk_dev_xyz789

# Staging
BROWSERMAN_API_KEY=sk_staging_abc123

# Production
BROWSERMAN_API_KEY=sk_live_def456

5. Limit Key Permissions

When creating a service key, grant minimum required permissions:

{
  "name": "CI/CD Pipeline",
  "permissions": {
    "accounts": ["read"],
    "tasks": ["create", "read"],
    "platforms": ["read"]
  }
}

6. Monitor API Key Usage

Regularly review API key activity:

1. Go to Settings > API Keys
2. Check Last Used timestamps
3. Review Request Count
4. Revoke unused keys

7. Set Up Alerts

Configure alerts for suspicious activity:

• Unusual request patterns
• Requests from unexpected locations
• High error rates
• Rate limit violations

Managing API Keys

List Your Keys

View all your API keys in the dashboard:

1. Go to Settings > API Keys
2. See all active keys with their:
   • Name
   • Created date
   • Last used date
   • Request count
   • Status

Revoke a Key

To revoke an API key:

1. Go to Settings > API Keys
2. Find the key to revoke
3. Click Revoke or Delete
4. Confirm the action

Note: Revoking a key is immediate and cannot be undone. Any applications using this key will stop working immediately.

Rename a Key

To rename an API key:

1. Go to Settings > API Keys
2. Click on the key name
3. Enter a new name
4. Save changes

Rate Limits

API keys are subject to rate limits based on your plan:

Free Plan

• 100 requests per hour
• 1,000 requests per day
• 10,000 requests per month

Pro Plan

• 1,000 requests per hour
• 10,000 requests per day
• 100,000 requests per month

Enterprise Plan

• Custom limits
• Dedicated support
• SLA guarantees

Rate Limit Headers

Check rate limit status in response headers:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 995
X-RateLimit-Reset: 1642248000

JavaScript example:

const response = await fetch('https://api.browserman.run/api/platforms', {
  headers: { 'Authorization': `Bearer ${API_KEY}` }
});

const remaining = response.headers.get('X-RateLimit-Remaining');
const reset = response.headers.get('X-RateLimit-Reset');

console.log(`Remaining requests: ${remaining}`);
console.log(`Resets at: ${new Date(reset * 1000)}`);

Handling Rate Limits

Implement backoff:

async function makeRequestWithBackoff(url, options) {
  const response = await fetch(url, options);

  if (response.status === 429) {
    const resetTime = response.headers.get('X-RateLimit-Reset');
    const waitTime = (resetTime * 1000) - Date.now();

    console.log(`Rate limited. Waiting ${waitTime}ms`);
    await sleep(waitTime);

    return makeRequestWithBackoff(url, options);
  }

  return response;
}

OAuth for Account Binding

While API keys authenticate your application, OAuth is used to connect social media accounts to Browserman.

OAuth Flow

1. Request Authorization URL

   POST /api/accounts/oauth/authorize

2. Redirect User

   • Send user to the authorization URL
   • User logs in on the platform
   • User grants permissions

3. Complete Authorization

   POST /api/accounts/oauth/callback

See Account Binding for detailed OAuth instructions.

Troubleshooting

Invalid API Key

Error:

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid API key"
  }
}

Solutions:

1. Verify key is correct
2. Check for extra spaces or characters
3. Ensure key hasn't been revoked
4. Generate a new key if needed

Expired API Key

API keys don't expire automatically, but they can be manually revoked.

If your key stops working:

1. Check if it was revoked
2. Generate a new key
3. Update your applications

Rate Limited

Error:

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Too many requests. Try again in 3600 seconds."
  }
}

Solutions:

1. Wait for rate limit to reset
2. Implement request throttling
3. Upgrade to higher plan
4. Contact support for temporary increase

Wrong Permissions

Error:

{
  "error": {
    "code": "FORBIDDEN",
    "message": "Insufficient permissions"
  }
}

Solutions:

1. Check key permissions in dashboard
2. Use a key with appropriate permissions
3. Contact support if you need different permissions

Security Checklist

Before deploying to production:

• [ ] API keys stored in environment variables
• [ ] Separate keys for dev/staging/production
• [ ] Keys never committed to version control
• [ ] Implemented rate limit handling
• [ ] Set up monitoring and alerts
• [ ] Documented key rotation process
• [ ] Revoked any unused or test keys
• [ ] Configured minimum required permissions
• [ ] Enabled two-factor authentication on account
• [ ] Reviewed and understood security policies

Next Steps

• Account Binding Guide
• API Overview
• MCP Configuration
• Best Practices