Skip to main content

​
Overview

Partners and agent integrations require authentication to access platform resources. This guide covers API key setup and customer account discovery for multi-account management.

​
API Key Setup

All API requests require an API key in the Authorization header: 
Authorization: Bearer YOUR_API_KEY
API Key Security:
  • Get your Scope3 API key: Get one here
  • Use HTTPS only - never send keys over HTTP
  • Store keys securely and rotate regularly
  • Provider API keys provide access to specific customer accounts based on your partner configuration

​
Discovering Manageable Customer Accounts

​
Check Customer Access

MCP Tool: signals/get-partner-seats Use this tool to discover which customer accounts your provider API key can manage data for: 
{
  "tool": "signals/get-partner-seats",
  "parameters": {}
}
Response includes:
  • Customer account ID and display name
  • Seat identifier for API operations
  • Access granted through provider-customer relationships
  • Management permissions scope

​
Using Customer Account Information

Once you know which customer accounts you can manage, you can: Filter operations by customer account: 
{
  "tool": "signals/list",
  "parameters": {
    "seatId": "seat_123"
  }
}
Manage customer-specific resources:
  • Customer signals and segments
  • Campaign configurations
  • Performance data access
  • Account-level settings

​
Authentication Scopes

Partner API keys provide different access levels:

​
Read Access

  • List accessible seats
  • View segments and signals
  • Read campaign performance data
  • Access reporting APIs

​
Write Access

  • Create and update segments
  • Attach data to segments
  • Register signals agents
  • Modify campaign configurations

​
Administrative Access

  • Manage API key permissions
  • Configure seat access controls
  • Set up webhook endpoints
  • Access audit logs

​
Multi-Customer Operations

When working across multiple customer accounts, operations automatically scope to your manageable accounts: List all segments across customer accounts: 
{
  "tool": "signals/list",
  "parameters": {}
}
Results include customer account information:
  • seatId - Unique seat identifier for API operations
  • seatName - Customer account display name
  • customerId - Internal customer account ID
  • Standard resource metadata
This enables you to understand which customer account owns each resource and manage data at the account level.

​
Error Handling

Common authentication errors:

​
Invalid API Key

{
  "error": "unauthorized",
  "message": "Invalid or expired API key"
}

​
Insufficient Permissions

{
  "error": "forbidden", 
  "message": "Provider account does not have access to requested customer account"
}

​
Customer Account Not Found

{
  "error": "customer_not_found",
  "message": "Customer account 'seat_xyz' not found or not manageable"
}

​
Sales Agent & Signals Agent Authentication

Sales agents and signals agents support multiple authentication mechanisms for secure communication with publisher endpoints. This section covers how to register agents with authentication and the approval process for live inventory access.

​
Supported Authentication Types

The platform supports four authentication mechanisms for agent integrations:

​
Bearer Token Authentication

Simple token-based authentication using HTTP Authorization headers. Configuration Example: 
{
  "tool": "sales_agents_register",
  "parameters": {
    "name": "Publisher Direct Sales",
    "endpoint_url": "https://publisher.com/adcp",
    "auth_config": {
      "type": "bearer",
      "token": "your_bearer_token_here"
    }
  }
}

​
OAuth 2.0 Authentication

Automatic OAuth 2.0 authentication using publisher discovery and client registration. Configuration Example: 
{
  "tool": "sales_agents_register", 
  "parameters": {
    "name": "OAuth Publisher Integration",
    "endpoint_url": "https://publisher.com/adcp",
    "auth_config": {
      "type": "oauth",
      "issuer": "https://publisher.com",
      "scope": "adcp.read adcp.write"
    }
  }
}
The system automatically:
  • Discovers OAuth endpoints via .well-known protocols
  • Registers Scope3 as an authorized client with the publisher
  • Manages token refresh and caching
Automatic OAuth Setup: Scope3 handles all OAuth client registration and credential management. You only need to provide the publisher’s OAuth issuer domain.

​
Custom Headers Authentication

Custom header-based authentication (e.g., API keys in custom headers). Configuration Example: 
{
  "tool": "sales_agents_register",
  "parameters": {
    "name": "API Key Publisher",
    "endpoint_url": "https://publisher.com/adcp", 
    "auth_config": {
      "type": "custom_header",
      "headerName": "x-api-key",
      "headerValue": "your_api_key_value"
    }
  }
}

​
Custom Integrations

Scope3 can build custom authentication integrations for specific publishers with unique authentication requirements.
Custom Integration Development: For publishers requiring specialized authentication flows (like proprietary JWT schemes), contact Scope3 to discuss custom integration development. These integrations are built on a case-by-case basis.

​
Registration Process

​
For Sales Agents

Use the sales_agents_register tool with authentication configuration: 
{
  "tool": "sales_agents_register",
  "parameters": {
    "name": "Publisher Sales Team",
    "endpoint_url": "https://publisher.com/adcp",
    "account_identifier": "your_publisher_account_id",
    "description": "Direct sales integration with Publisher",
    "auth_config": {
      "type": "bearer",
      "token": "secure_bearer_token"
    }
  }
}

​
For Signals Agents

Use the signals_agent_register tool with optional authentication in config: 
{
  "tool": "signals_agent_register",
  "parameters": {
    "name": "Publisher Signals Agent",
    "endpointUrl": "https://publisher.com/signals",
    "brandAgentId": "brand_agent_123",
    "description": "Automated audience signals from Publisher",
    "config": {
      "auth_type": "oauth",
      "issuer": "https://publisher.com"
    }
  }
}
Business Approval Required: All sales agents added by customers require Scope3 testing and approval before accessing live inventory. This ensures:
  • Technical compatibility with publisher endpoints
  • Authentication security validation
  • Compliance with platform standards
  • Quality assurance for production use
Contact your Scope3 representative to initiate the approval process after registration.

​
Next Steps

After authentication setup:

Segment Management

Manage SegmentsCreate, list, and update audience segments across your accessible seats.

Data Attachment

Attach DataUpload audience data using real-time APIs or CSV file uploads.