Authentication

Interchange uses WorkOS as its credential control plane. Interactive connectors use OAuth, AI agents can use Agent Registration, simple customer automation uses organization API keys, and backend integrations that require OAuth client credentials can use M2M applications. New standalone buyer organizations are admitted in stages. When buyer admission is closed, selecting Advertiser during signup opens the buyer preview form. It asks whether the buyer is a brand or agency, which countries and channels they plan to buy, their estimated pilot budget and timing, their self-service buying experience, and whether they are comfortable testing a pre-launch product with support in Slack. Buyers whose plans match a live pilot market and channel are sent for solutions review; buyers outside the current markets stay on the launch list under the exact countries they selected. Those country-level signals guide where Interchange expands next; selecting a country does not claim that a pilot is already open there. When a work-email domain already belongs to a known organization, Interchange associates the preview request with that organization and pre-fills its canonical name. This does not grant membership in an existing account: an invitation or the account’s normal domain-approval policy is still required for access. When admission is open, the same signup creates the buyer organization and then offers three starting points: work in Interchange, build with the API, or connect an assistant. Choosing one does not remove access to the other two. Public Storefront account creation is independent from the Organization IU Rate Card rollout. A Storefront prospect can accept Scope3’s standard Terms of Service and create an account even when IU plan selection is unavailable. That acceptance creates the account’s standard agreement; it does not publish or accept an IU Rate Card, enroll the organization in a paid IU plan, grant setup credit, or enable IU charging. When the IU rollout is closed, signup does not show pricing previews or signup-code entry and rejects clients that try to submit IU plan or signup-code data. Custom signup clients can distinguish the states in the email-availability response: storefrontAccountSignupAllowed controls account creation and storefrontIuSignupAllowed controls the IU plan-selection step. The legacy storefrontSignupAllowed field retains its IU-step meaning during the transition. An organization invitation is a separate, org-scoped path. Its recipient can create an account and join the named organization even while public buyer signup is waitlisted. The invited organization must itself be admitted to the current rollout. The invitation does not create a second buyer organization, grant access to the wider marketplace by itself, or replace any Terms of Service, account, or spend requirements on the invited organization. Seller join links are different: they are reusable links that create sponsored buyers scoped to one storefront.

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.

MCP protocol compatibility

The buyer and storefront MCP endpoints support both stateless MCP 2026-07-28 requests and the existing initialize/session lifecycle. MCP clients negotiate the protocol automatically; users do not enable a setting or repeat OAuth authorization to opt in. Existing connectors continue working unchanged. Specialized Murph, creative, admin, TARS, and dynamic platform-storefront MCP endpoints remain on the session lifecycle during the staged rollout.

API Keys

For CLI tools, scripts, shared automation, and direct REST API integrations, use an organization API key unless the integration specifically requires OAuth client credentials.

Getting Your API Key

Visit interchange.io/user-api-keys
Sign up or log into your Interchange account as an organization admin
Select Account API keys
Create a key and select only the permissions the integration needs
Copy the key when WorkOS displays it

Keep your API key secure! Don’t commit it to version control or share it publicly. Use environment variables or secure key management systems.

Org API Keys

Organization API keys are owned by the organization rather than an individual user. WorkOS creates, stores, masks, and revokes the keys; Interchange resolves the organization and applies its resource, entitlement, standing, governance, and spend policies.

Permissions

Each org API key carries one or more permission scopes:

Permission	What it grants
`buyer:read`	Read campaigns, advertisers, reports
`buyer:write`	Create and modify campaigns and tactics
`buyer:admin`	Org settings, user management, delete
`account:admin`	Billing, contracts, teams

Principle of least privilege: issue each key with only the permissions it needs.

Managing keys

# List keys for your org
curl -X GET "https://api.interchange.io/api/v2/org-api-keys" \
  -H "Authorization: Bearer your_user_access_token_here"

# Create a key with read-only access
curl -X POST "https://api.interchange.io/api/v2/org-api-keys" \
  -H "Authorization: Bearer your_user_access_token_here" \
  -H "Content-Type: application/json" \
  -d '{"name": "reporting-bot", "permissions": ["buyer:read"]}'

# Revoke a key
curl -X DELETE "https://api.interchange.io/api/v2/org-api-keys/key_abc123" \
  -H "Authorization: Bearer your_user_access_token_here"

All three endpoints require an interactive human session with buyer:admin; an API key or M2M token cannot create another credential. The Interchange Account API keys settings tab embeds the WorkOS API Keys widget. The widget displays a key in full only when it is created; later views show a masked value. Organization admins can inspect and revoke keys there. Organization keys can select buyer:read, buyer:write, and buyer:admin; account:admin is not delegatable through the widget. Customers that still have a scope3_ API key see a Legacy API keys section below the WorkOS widget. Account administrators see both user keys and older customer-scoped keys so working account-level legacy credentials remain visible during migration; other users see only their own keys. Settings no longer offers creation, editing, or secret reveal for those keys. Create an organization API key, update and verify the integration that uses the legacy key, and then revoke it. Existing legacy keys continue to authenticate until they expire or are revoked. Applications embedding the same management surface can request a short-lived widget session token:

curl -X GET "https://api.interchange.io/api/v2/org-api-keys/widget-token" \
  -H "Authorization: Bearer your_user_access_token_here"

The response requires an interactive WorkOS user session and includes a short-lived token for the WorkOS frontend widget. Never expose the WorkOS server API key to a browser.

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 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"]

Agent Registration

An agent that has no credential starts with https://api.interchange.io/auth.md. The guide is generated by WorkOS and describes anonymous registration, the optional user claim ceremony, and assertion exchange. Anonymous registrations receive a short-lived WorkOS access token and can reach only the zero-spend Interchange sandbox. This bounded anonymous trial does not require an organization to accept Terms of Service because the agent is not associated with a customer yet. Before claim, the only customer-data API reads are GET|HEAD /api/v2/buyer/advertisers[/:id]; all mutations, nested advertiser routes, MCP calls, and money-moving routes are denied. Access to customer data or write operations requires a service_auth claim completed by the customer user; after claim, the customer must satisfy Terms of Service, account grants, commercial entitlements, governance, and spend controls.

M2M Applications

Use an M2M application when a deployed customer backend requires the OAuth 2.0 client_credentials flow and short-lived JWT access tokens. An organization admin can manage applications through /api/v2/m2m-applications; creation returns the client secret once, together with the WorkOS token endpoint and Interchange resource indicator. The token endpoint is hosted on Interchange’s AuthKit domain for the environment. Store the secret in a secrets manager. M2M applications support overlapping client secrets for rotation. Revoke the old secret only after the new secret has successfully obtained and used an access token. Deleting the application immediately disables its local Interchange customer association; already-issued access tokens are rejected locally even if they have not expired.

Legacy `scope3_` Keys

Existing scope3_ keys remain accepted during the credential migration and can still be revoked. They are compatibility credentials, not the target for new integrations. Do not replace a working key until its WorkOS replacement has made a successful test call. Interchange will publish any retirement date only after owners, usage telemetry, customer communication, and rollback readiness meet the retirement gate.

MCP Authentication

For AI agent integrations using the Model Context Protocol:

An MCP agent cannot retrieve an existing API key or M2M client secret, and it must not mint or carry a new long-lived secret in chat. For an organization API key, the agent directs a human organization admin to Settings → API Access. M2M does not have a management widget yet; a human admin or their developer uses the documented /api/v2/m2m-applications lifecycle with an interactive human session. The human copies the one-time secret directly into the workload’s secret manager. The workload then uses the API key, or exchanges an M2M client secret for short-lived access tokens.

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="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 organization must accept Scope3’s Terms of Service before its authenticated members can use most of the API surface. ToS acceptance applies to the organization, not the individual. Accounts under a parent organization inherit the parent’s governing agreement; they do not accept separate account-level terms. Once a direct parent-organization ADMIN accepts, the organization and its accounts are unblocked. Only a direct ADMIN or SUPER_ADMIN UserPermission on the organization that owns the governing agreement is permitted to accept its ToS via POST /api/v2/accept-tos (or the accept_tos MCP tool).

An account member who is not a direct admin of its parent organization cannot accept the parent’s ToS. They must join the parent organization as an admin first.
A direct member at a non-admin level (BASIC, PREMIUM) also cannot accept — only ADMIN / SUPER_ADMIN levels qualify.

Pending organization invitations remain available while ToS is outstanding. Open the account selector, choose the pending invitation, and accept or decline it. Accepting an admin invitation creates the direct organization membership needed to review and accept the organization’s ToS; the ToS prompt does not block the invitation page.

When updated terms are published

When updated Terms of Service appear in Interchange, the required action depends on the kind of change:

A patch that does not materially change the terms, or is wholly favorable to customers, is a notice-only update. Existing acceptance continues without an interruption.
A material minor or major update requires an organization administrator to accept. Before the displayed deadline, eligible administrators see the review prompt and can choose Review later; other members can continue working during that review period.
Once the deadline passes, account activity pauses until an eligible administrator accepts. Non-admin members then see a notice telling them to contact an administrator, while the account selector remains available.

Accepting a minor update keeps the existing commercial contract and any negotiated pricing attached to it. A major update does not silently replace custom commercial terms; Scope3 coordinates that change separately. REST and MCP integrations can read the transition in the tosUpdate object on current-user and account-switch responses. Its action is notice, acceptance_due, or acceptance_required, with the target version, deadline, terms URL, and change-summary URL. If Interchange cannot verify agreement status, protected actions return a retryable service error rather than proceeding without confirmed terms. 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 shows a blocking notice. The global account selector remains available so the user can switch to an unblocked organization or accept a pending organization invitation. /auth/me also returns contractBlockReason when the active account cannot transact, and omits it when the account is in good standing:

`contractBlockReason`	Meaning
`no_contract`	The account has no active contract with Scope3. Accepting the Terms of Service creates one.
`tos_not_accepted`	The account is on standard terms it has not accepted — either it accepted an older version, or Scope3 set it up on standard terms and nobody at the account has accepted them yet.
`organization_contract_missing`	The account inherits its parent organization’s contract, and the organization has no active one. An organization admin must accept on its behalf.

showTosBox answers “must this session be blocked”; contractBlockReason answers “why can this account not transact”. They differ for a Scope3 SuperAdmin working inside a customer account: that session is deliberately not blocked (showTosBox: false), but the reason is still reported so the operator sees the state a real user of that account would hit. See the Adding an account section of the Buyer Onboarding guide for the full account-creation 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.

Welcome

Core Concepts

Connect

Cross-Cutting Reference

Release Notes

Authentication

Authentication

OAuth (Recommended for AI Agents)

MCP protocol compatibility

API Keys

Getting Your API Key

Org API Keys

Permissions

Managing keys

Embedded key management widget

Using Your API Key

Agent Registration

M2M Applications

Legacy `scope3_` Keys

MCP Authentication

Base URLs

Versioning

Terms of Service acceptance

When updated terms are published

Next Steps

Quick Start

Built for Agents

SSO Setup

​Authentication

​Buyer signup and organization invitations

​Storefront signup and IU plans

​OAuth (Recommended for AI Agents)

​MCP protocol compatibility

​API Keys

​Getting Your API Key

​Org API Keys

​Permissions

​Managing keys

​Embedded key management widget

​Using Your API Key

​Agent Registration

​M2M Applications

​Legacy scope3_ Keys

​MCP Authentication

​Base URLs

​Versioning

​Terms of Service acceptance

​When updated terms are published

​Next Steps

Quick Start

Built for Agents

SSO Setup

Authentication

Buyer signup and organization invitations

Storefront signup and IU plans

OAuth (Recommended for AI Agents)

MCP protocol compatibility

API Keys

Getting Your API Key

Org API Keys

Permissions

Managing keys

Embedded key management widget

Using Your API Key

Agent Registration

M2M Applications

Legacy `scope3_` Keys

MCP Authentication

Base URLs

Versioning

Terms of Service acceptance

When updated terms are published

Next Steps