Skip to main content
POST /api/v2/storefront/agents/{agentId}/accounts/oauth/authorize Initiates the OAuth flow for per-account agent registration. The resulting tokens are stored against the buyer/operator account the OAuth grant represents — not in the shared agent configuration. The response returns an authorizationUrl to send the operator to. Use this when an OAuth agent needs distinct credentials per buyer account rather than one platform-level token.

​
Request

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

​
Parameters

FieldTypeRequiredNotes
agentIdstringYesAgent identifier (path parameter)
accountIdentifierstringNoAccount identifier for the OAuth flow. When omitted, the platform uses a placeholder identifier you can rename later

​
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_acme123",
  "agentId": "agt_premium_ctv",
  "agentName": "Premium CTV — Direct"
}
Send the operator to authorizationUrl. After consent completes, the platform stores the tokens against the buyer/operator account. Re-fetch the agent with Get agent to confirm hasCustomerAccount: true.

​
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 agent OAuth

Agent-level token flow instead

Get agent

Confirm the account is registered

Agents overview

OAuth flow concepts