Authentication

The Interchange API supports two authentication methods: OAuth for AI agent connectors and API keys for programmatic integrations.

OAuth (Recommended for AI Agents)

When connecting through Claude Connectors or ChatGPT MCP Connectors, authentication is handled automatically via OAuth. Users log in with their Scope3 credentials and the agent receives a secure token.

No API keys to create or manage
Tokens are scoped to the authenticated user
Works with Claude.ai (Team/Enterprise), Claude Desktop, and ChatGPT

See the Built for Agents guide for setup instructions.

API Keys

For CLI tools (Claude Code, Cursor), custom agents, and direct REST API integrations, use an API key.

Getting Your API Key

Visit interchange.io/user-api-keys
Sign up or log into your Scope3 account
Generate a new API key for your integration
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_<client_id>_<secret>

Using Your API Key

Pass the key as a Bearer token in the Authorization header:

curl
TypeScript
Python

curl -X GET "https://api.interchange.io/api/v2/buyer/advertisers" \
  -H "Authorization: Bearer scope3_your_api_key_here" \
  -H "Content-Type: application/json"

const response = await fetch(
  'https://api.interchange.io/api/v2/buyer/advertisers',
  {
    headers: {
      'Authorization': `Bearer ${process.env.SCOPE3_API_KEY}`,
      'Content-Type': 'application/json',
    },
  }
);

const { data } = await response.json();

import requests
import os

response = requests.get(
    "https://api.interchange.io/api/v2/buyer/advertisers",
    headers={
        "Authorization": f"Bearer {os.environ['SCOPE3_API_KEY']}",
        "Content-Type": "application/json",
    },
)

data = response.json()["data"]

MCP Authentication

For AI agent integrations using the Model Context Protocol:

TypeScript
Python

import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { HttpClientTransport } from '@anthropic-ai/mcp-client-http';

const transport = new HttpClientTransport({
  url: 'https://api.interchange.io/mcp/buyer',
  headers: {
    'Authorization': `Bearer ${process.env.SCOPE3_API_KEY}`,
  },
});

const client = new Client({ name: 'my-agent', version: '1.0.0' });
await client.connect(transport);

const result = await client.callTool('health', {});

from mcp.client.streamable_http_transport import StreamableHttpTransport
from mcp.client import Client

transport = StreamableHttpTransport(
    "https://api.interchange.io/mcp/buyer",
    auth="scope3_your_api_key_here",
)

async with Client(transport) as client:
    result = await client.call_tool("health")

Base URLs

Type	Production
Buyer REST	`https://api.interchange.io/api/v2/buyer`
Storefront REST	`https://api.interchange.io/api/v2/storefront`
Buyer MCP	`https://api.interchange.io/mcp/buyer`
Canonical Storefront Agent URL	`https://interchange.io`

Programmatic API endpoints and buyer MCP are served at https://api.interchange.io. The canonical storefront agent URL is https://interchange.io. Discovery endpoints under /.well-known/* (JWKS, brand.json, OAuth/OIDC metadata) return the same response on both https://api.interchange.io and https://interchange.io.

Versioning

REST and MCP endpoints come in two forms — pick based on whether you want to pin to a specific major version or auto-roll with the platform.

Form	Example	Behavior	When to use
Versioned (canonical)	`/api/v2/buyer`, `/mcp/v2/buyer`	Pinned to v2. Will keep serving v2 even after a future v3 ships.	Production integrations, SDKs, anywhere a breaking change would silently break you.
Unversioned (alias)	`/api/buyer`, `/mcp/buyer`	308-redirects to whatever major version is currently stable (today: v2). Auto-rolls when a new major is cut.	Quick demos, links you don’t want to update, or environments where you actively want to follow latest.

The same pattern applies to storefront endpoints (/api/v2/storefront vs /api/storefront, /mcp/v2/storefront vs /mcp/storefront). The Base URLs table above lists the versioned form because it’s what we recommend for any integration you don’t plan to revisit on every major release.

Terms of Service acceptance

Every customer must accept Scope3’s Terms of Service before its authenticated members can use most of the API surface. ToS is bound to the customer, not the individual — once any direct ADMIN of the customer accepts, all of that customer’s members are unblocked. Only a direct ADMIN or SUPER_ADMIN UserPermission on the target customer is permitted to accept its ToS via POST /api/v2/accept-tos (or the accept_tos MCP tool).

A parent admin scoped into a child customer via the customer hierarchy has no direct UserPermission row on the child — they cannot accept its ToS. A direct admin of the child must sign in and accept.
A direct member at a non-admin level (BASIC, PREMIUM) also cannot accept — only ADMIN / SUPER_ADMIN levels qualify.

The user-info responses (/auth/me, POST /api/v2/accounts/switch, POST /api/v2/accounts/create-child, and the user_get_current MCP tool) include a canAcceptTos boolean reflecting this rule. When showTosBox: true but canAcceptTos: false, the UI suppresses the acceptance modal and routes the user to Account Settings, where Team and Communications (the surfaces needed to onboard a direct admin) remain available. See the Adding a child account section of the Buyer Onboarding guide for the full child-account flow.

Next Steps

Quick Start

Get up and running in minutes.

Built for Agents

Connect Claude, ChatGPT, Cursor, and more.

SSO Setup

Configure single sign-on for your organization.

​Authentication

​OAuth (Recommended for AI Agents)

​API Keys

​Getting Your API Key

​API Key Format

​Using Your API Key

​MCP Authentication

​Base URLs

​Versioning

​Terms of Service acceptance

​Next Steps

Quick Start

Built for Agents

SSO Setup

Authentication

OAuth (Recommended for AI Agents)

API Keys

Getting Your API Key

API Key Format

Using Your API Key

MCP Authentication

Base URLs

Versioning

Terms of Service acceptance

Next Steps