Skip to main content

​
Authentication

The Scope3 Agentic API uses API keys for authentication. All requests must include a valid API key to access your campaigns, creatives, and other resources.

​
Getting Your API Key

  1. Visit scope3.com/integrate/api-keys
  2. Sign up or log into your Scope3 account
  3. Generate a new API key for your integration
  4. Copy the key - it starts with scope3_
Keep your API key secure! Don’t commit it to version control or share it publicly. Use environment variables or secure key management systems.

​
API Key Format

Scope3 API keys follow this format: 
scope3_<32_character_client_id>_<secret>
Example: scope3_abc123def456ghi789jkl012mno345pq_xyz789

​
MCP Authentication

For Model Context Protocol integrations with AI agents like Claude, OpenAI, or Anthropic: Python (Claude Code): 
from mcp.client.streamable_http_transport import StreamableHttpTransport
from mcp.client import Client

transport = StreamableHttpTransport(
    "https://api.agentic.scope3.com/mcp", 
    auth="scope3_your_api_key_here",
)

async with Client(transport) as client:
    result = await client.call_tool('check_auth_status')
    print(result)  # ✅ Authenticated as [email protected]
Node.js: 
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";

const scope3_api_key = 'scope3_your_api_key_here';
const transport = new StreamableHTTPClientTransport(
  'https://api.agentic.scope3.com/mcp',
  {
    fetch: (url, init) => fetch(url, {
      ...init,
      headers: {
        ...init.headers,
        "x-scope3-api-key": scope3_api_key,
      },
    }),
  }
);

const client = new Client(...);
await client.connect(transport);

const result = await client.callTool('check_auth_status');
console.log(result); // ✅ Authenticated as [email protected]

​
Testing Authentication

Test your API key with the check_auth_status MCP tool: 
result = await client.call_tool('check_auth_status')
# ✅ Authenticated as [email protected] (Customer ID: 12345)
Tool Response: 
✅ Authenticated as [email protected] (Customer ID: 12345)

​
Security Model

​
Data Isolation

All API operations are automatically scoped to your Customer ID:
  • You can only access your own brand agents, campaigns, and creatives
  • Multi-tenant security prevents cross-customer data access
  • Agency accounts can manage multiple brand agents under one customer ID

​
Rate Limits

ResourceLimitNotes
API Requests1,000/hour per keyBurst allowance available
MCP Requests500/hour per keyAI agent usage
Data Exports50/hour per keyLarge report generation

​
Best Practices

  • Environment Variables: Never hardcode keys in source code
  • Key Rotation: Rotate API keys every 90 days
  • Least Privilege: Request only necessary permissions
  • Monitoring: Track API key usage for anomalies
  • 401 Unauthorized: Check if API key is valid and not expired
  • 403 Forbidden: Verify you have permission for the requested resource
  • 429 Too Many Requests: Implement exponential backoff retry logic
  • HTTPS Only: All API calls must use HTTPS
  • Secure Storage: Use secure key management (AWS Secrets Manager, Azure Key Vault, etc.)
  • Logging: Log authentication failures for security monitoring
  • Backup Keys: Keep backup API keys for continuity

​
Common Error Scenarios

​
Invalid API Key

HTTP/1.1 401 Unauthorized
{
  "error": "Invalid or expired API key",
  "code": "AUTH_INVALID_KEY"
}
Solution: Check your API key format and generate a new one if needed.

​
Missing Authentication

HTTP/1.1 401 Unauthorized
{
  "error": "Missing authentication",
  "code": "AUTH_MISSING"
}
Solution: Include your API key in the MCP transport configuration.

​
Rate Limit Exceeded

HTTP/1.1 429 Too Many Requests
{
  "error": "Rate limit exceeded",
  "code": "RATE_LIMIT_EXCEEDED",
  "resetTime": "2024-01-15T10:30:00Z"
}
Solution: Wait until resetTime or implement exponential backoff.

​
Next Steps

Quick Start Guide

Create your first campaign with authentication setup

Brand Agents

Set up your advertiser account after authentication

API Reference

Complete authentication endpoint documentation

MCP Integration

Use with Claude, ChatGPT, and other AI assistants