Authentication
Social Neuron supports three authentication methods for the MCP server. All methods produce an API key that grants access based on your plan's scope.
Authentication Methods
Device Code Flow (Recommended)
Best for local development. A browser window opens, you approve, and the CLI receives your API key automatically.
Code
How it works under the hood:
- The CLI requests a device code from the authorization server
- Your browser opens to the authorization page with a user code
- You log in and approve the requested scopes
- The CLI polls the authorization server until approval completes
- The API key is returned and stored in your OS keychain
Browser OAuth Flow
Standard browser-based OAuth for environments that support redirects.
Code
API Key Paste
Generate a key in the Social Neuron dashboard and paste it into the CLI. Best for CI/CD pipelines and automated workflows.
Code
Generate your key at socialneuron.com/settings/developer.
Key Storage
API keys are stored securely using OS-native mechanisms:
| Platform | Storage | Details |
|---|---|---|
| macOS | Keychain | security add-generic-password |
| Linux | secret-tool (libsecret) | D-Bus Secret Service API |
| Windows / fallback | ~/.config/social-neuron/credentials.json | chmod 0600 |
| CI/headless | SOCIALNEURON_API_KEY env var | Highest priority |
Keys are never written to disk in plaintext. The environment variable (SOCIALNEURON_API_KEY) takes highest priority and is the recommended approach for CI/CD.
Scopes
Each API key is assigned scopes that control which operations it can perform. Scopes are determined by your subscription plan.
| Scope | Permissions |
|---|---|
mcp:full | All operations (includes all scopes below) |
mcp:read | Analytics, insights, brand profiles, content plans, quality checks, usage stats, credit balance |
mcp:write | Generate content (video, image, voiceover, carousel), create storyboards, save brand profiles, plan content |
mcp:distribute | Schedule posts, publish content plans |
mcp:analytics | Refresh analytics, YouTube deep analytics |
mcp:comments | List, reply, post, moderate, delete comments |
mcp:autopilot | Configure and monitor automated scheduling |
Scopes by Plan
| Plan | Scopes |
|---|---|
| Free | No API access |
| Trial | No API access |
| Starter ($19/mo) | No API access |
| Pro ($49/mo) | mcp:read, mcp:analytics |
| Team ($99/mo) | mcp:full |
| Agency ($249/mo) | mcp:full + multi-brand + REST API |
Rate Limits
Rate limits are enforced per API key by category:
| Category | Limit |
|---|---|
| Text generation | 30 requests/min |
| Image generation | 10 requests/min |
| Video generation | 5 requests/min |
| Analytics queries | 60 requests/min |
| All other endpoints | 60 requests/min |
A global IP-based limit of 60 requests/min also applies. Max API keys per plan: Starter (2), Pro (5), Team (20).
Every response includes rate limit headers:
X-RateLimit-Remaining-- Requests remaining in the current windowX-RateLimit-Reset-- Unix timestamp when the window resets
Exceeding the limit returns HTTP 429. Wait until X-RateLimit-Reset before retrying.
Generation-heavy tools (video, image) have additional per-tool rate limits of 20 requests per minute to prevent runaway automation.
Security
- All API keys are SHA-256 hashed before storage -- we never store plaintext keys
- SSRF protection on all URL parameters with DNS rebinding prevention
- Agent loop detection prevents runaway automation
- Gateway token system ensures all requests flow through scope and credit enforcement
Disabling Telemetry
The MCP server collects anonymous usage metrics (tool name, duration, success/failure). Your user ID is hashed before transmission. No content, API keys, or request payloads are collected.
To disable:
Code