> ## Documentation Index
> Fetch the complete documentation index at: https://docs.interchange.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Start account OAuth

> Begin the per-account OAuth flow and get an authorization URL

`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

```bash curl theme={null}
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

| Field               | Type   | Required | Notes                                                                                                                |
| ------------------- | ------ | -------- | -------------------------------------------------------------------------------------------------------------------- |
| `agentId`           | string | Yes      | Agent identifier (path parameter)                                                                                    |
| `accountIdentifier` | string | No       | Account identifier for the OAuth flow. When omitted, the platform uses a placeholder identifier you can rename later |

## Response

```json theme={null}
{
  "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](/v2/storefront/agents/tasks/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](/v2/reference/errors) for the full error contract.

## Related

<CardGroup cols={2}>
  <Card title="Agent tasks" href="/v2/storefront/agents/tasks" icon="list-check">
    All agent operations
  </Card>

  <Card title="Start agent OAuth" href="/v2/storefront/agents/tasks/start-agent-oauth" icon="key">
    Agent-level token flow instead
  </Card>

  <Card title="Get agent" href="/v2/storefront/agents/tasks/get-agent" icon="magnifying-glass">
    Confirm the account is registered
  </Card>

  <Card title="Agents overview" href="/v2/storefront/agents/overview" icon="robot">
    OAuth flow concepts
  </Card>
</CardGroup>