Skip to main content
POST /api/v2/storefront/agents/{agentId}/oauth/authorize Initiates the OAuth flow for agent-level setup. The resulting tokens are stored in the agent configuration and used by the platform when it calls the agent. The response returns an authorizationUrl — send the operator there to grant consent. Use this for agents whose authenticationType is OAUTH and whose tokens are platform-scoped, not tied to a single buyer account.

​
Request

curl
curl -X POST \
  "https://api.interchange.io/api/v2/storefront/agents/agt_premium_ctv/oauth/authorize" \
  -H "Authorization: Bearer $SCOPE3_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

​
Parameters

FieldTypeRequiredNotes
agentIdstringYesAgent identifier (path parameter)

​
Response

{
  "authorizationUrl": "https://idp.premium-ctv.example.com/oauth/authorize?client_id=...&redirect_uri=https%3A%2F%2Fapi.interchange.io%2Fapi%2Fv2%2Fstorefront%2Foauth%2Fcallback&state=pending_abc123",
  "agentId": "agt_premium_ctv",
  "agentName": "Premium CTV — Direct"
}
Send the operator to authorizationUrl. After the publisher’s IdP authenticates and the consent flow completes, the platform stores the tokens against the agent configuration. Re-fetch the agent with Get agent to confirm authConfigured (summary) or that the oauth block is cleared.

​
Errors

  • 400 VALIDATION_ERROR — the agent does not use OAuth, or redirectUri is not a valid URI.
  • 404 NOT_FOUND — no agent with that agentId is visible to the authenticated seller.
See Errors for the full error contract.

Agent tasks

All agent operations

Start account OAuth

Per-account token flow instead

Get agent

Confirm auth is configured

Agents overview

OAuth flow concepts