> ## 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. # Manage buyer agents > Add connected software agents to your buyer organization and manage their access, connections, and credentials. ## What a buyer agent is A **buyer agent** is a connected software actor installed in your buyer organization. It is not a person, and no person is assigned to or represented by an agent. Agents sit alongside Advertisers in the buyer workspace. The product keeps six concepts separate: * **Agent** — the software actor you recognize by name and purpose. * **Installation** — that agent's presence in your organization. * **Principal** — the durable internal identity Interchange uses for routing and audit. Most people only need it when troubleshooting. * **Credential** — how the software proves its identity. Secrets are shown once and are never displayed again. * **Connection** — a configured way for the agent to connect to Interchange, exchange data, or use an organization-owned reporting resource. * **Grant** — explicit permission to act for an advertiser or account. An installation, principal, credential, or connection is not a grant. Adding an agent does not grant advertiser, account, spend, payment, Terms, or other business authority. Until an administrator grants access through a supported workflow, the agent shows **No advertiser access**. The Agents area is designed for two operation modes under that same model: * **External agent** — software operated outside Interchange and connected through the supported principal, credential, and connection flows. * **Interchange-hosted agent** — software whose runtime is provisioned and monitored by Interchange. The supported Add agent flows currently connect external software. Hosted creation is not shown until its production installation and provisioning API is available; a local development runtime is not an organization registry. ## Before you start Only a person who is signed in directly as an administrator of the organization can read or change any of this. A support session, an impersonated or simulated session, a delegated session, an API key, and an OAuth client are all refused — including for reads. The organization is always resolved from who you are signed in as; a request cannot name a different organization, and it can never reach another organization's principals. Use the shared V2 base URL: ```bash theme={null} BASE=https://api.interchange.io/api/v2 AUTH='Authorization: Bearer ' ``` ## Identity and credentials Interchange issues each principal an opaque `principal_id` (for example `prin_yq8Kd…`). That is the **only** identifier that identifies the principal. It is a routing and audit handle: it is not a credential, and holding it grants nothing. Everything else attached to a principal is a **credential fact** — an OAuth client ID, an API key ID, an issuer URL, a WorkOS organization ID, a domain, a `brand.json` or JWKS URL, a signing key ID, a key fingerprint. Credential facts identify a *credential*, never the principal. Rotating or replacing a credential changes its facts and keeps the same `principal_id`; two credentials bound to the same buyer agent share one `principal_id` and have different facts. A principal also has a **kind** and a **lifecycle state**: * **Buyer agent** — one automation your organization runs. It holds credentials, and you administer those credentials. * **Organization operator** — your organization acting as itself, created the first time an organization credential calls Interchange. It is not a buyer agent and has no credentials to administer. * **Lifecycle state** is `active`, `suspended`, or `retired`. A buyer agent is suspended when it has no active credential left; every call it makes is then refused until you add one. Its `principal_id` is retained for audit and is never reissued. **Identity is not authority.** Every principal reports empty authority, on every response. Holding a principal or a credential gives no advertiser, account, spend, payment, or Terms access. Those come from separate grants and are never implied by identity. ## Manage buyer agents in the console Interchange's buyer console has an **Agents** page at `//buyer-agents`. It shows, for the organization you are signed in to: * each agent's name, connection status, advertiser access, and useful recent activity; purpose and operator information are labeled unavailable until an agent-scoped authoritative source supplies them; * an agent detail page organized into **Overview**, **Access**, **Connections**, **Notifications**, **Activity**, and **Settings**; * safe credential facts and management actions in Settings. The Overview answers what the agent is, who operates it when that information is available, whether it is connected, what it can do, and what needs attention. Access lists exact capabilities and grants. Connections contains the Interchange connection and organization-owned reporting and data resources. Notifications contains machine-event subscriptions into the agent. It does not turn an organization-owned Slack, email, or inbox destination into a subscription. Activity keeps platform state effects distinct from exact actor records for actions taken by human administrators. The organization roster's separate **operator principal** represents the organization acting as itself. It is not the signed-in human administrator, the operator of every agent, or an identity attributed to an agent. Until an agent-scoped source provides authoritative operator metadata, the agent Overview says that operator information is unavailable. Internal identifiers, protocol versions, configuration versions, destination generations, proof mechanics, and raw technical state are available only in the collapsed **Advanced diagnostics** section. The page never shows a credential secret. A secret is delivered exactly once, by the issue or rotate response itself, and cannot be retrieved afterwards — not by the console, not by the API, and not by support. From that page you can: * **Issue a credential** — Interchange creates a new identity-only OAuth client and shows its secret once. * **Register an existing credential** — bind an API key or OAuth client your organization already owns to a new buyer agent. Registration does not change what that credential could already do. * **Rotate an API key** — Interchange creates the replacement, shows its secret once, and retires the current key. * **Revoke a credential** — the credential stops authenticating immediately. Rotation and revocation both retire a live credential, so both require you to retype the buyer agent's name before the action is available. Before you confirm, the console states what will happen — including, for revocation, whether this is the buyer agent's **last active credential**. Revoking the last active credential suspends that buyer agent, and revocation cannot be undone: the same credential can never be registered again. ## Read your organization's principals ```bash theme={null} curl "$BASE/buyer-agent-principals" -H "$AUTH" ``` The response has two separate collections. `operator` is your organization operator principal, or `null` if one has not been created yet — it carries no credentials. `buyerAgents` lists each buyer agent with its `principalId`, `principalKind`, `displayName`, `lifecycleState`, `registeredAt`, `activeCredentialCount`, `authority`, and its `credentials`. Each credential carries `credentialType`, `bindingState`, `boundAt`, `lastVerifiedAt`, `retiredAt`, and an `administrationHandle` — the one non-secret selector the rotate and revoke calls accept (`{"type":"api_key","serviceTokenId":"…"}` or `{"type":"workos_m2m","subject":"…"}`). It is `null` for a credential type this endpoint does not administer. The read returns no secret, and it does not return issuer URLs, WorkOS organization IDs, access client IDs, domains, `brand.json` or JWKS URLs, signing key IDs, or key fingerprints. Those are credential facts, not identity, and this surface does not carry them. Responses are marked `private, no-store`. ## Set advertiser access An administrator grants access to exact advertisers through the buyer-agent principals REST API. `READ` permits advertiser reads; `READ_WRITE` permits reads and writes. Access is never inferred from registration, a credential, organization membership, or an account switch. The API replaces the full exact set in one request. First read the current `access.accessRevision`, then send it as `expectedAccessRevision`; a concurrent change returns `409` and you should reload before trying again. ```bash theme={null} curl -X PUT "$BASE/buyer-agent-principals//access" \ -H "$AUTH" -H 'Content-Type: application/json' \ -d '{"expectedAccessRevision":3,"advertisers":[{"advertiserId":"42","role":"READ"}]}' ``` The response returns `access.accessRevision` and the resolved advertiser names. Removing an advertiser revokes its active grant; changing a role records a revocation and a new grant for the new role. Each advertiser operation checks the active grant again. Advertisers delegated from another customer are not available to a buyer agent's request-time API operations. ### What a grant allows * Grants name advertisers your organization owns. The request is rejected when it names an advertiser owned by another customer or an archived advertiser. * A buyer agent works under one selected advertiser at a time, chosen with the `X-SCOPE3-SEAT-ID` header on REST or the advertiser selection on MCP. Selecting an advertiser without an active grant is refused. * `READ` allows reads of that advertiser's campaigns, creatives, media buys, and reporting. Any write with a `READ` grant is refused with `agent_read_only`. `READ_WRITE` allows writes as well. * Objects addressed by id (a campaign, creative, or media buy) must belong to the selected advertiser; lists that are not filtered by advertiser return only the selected advertiser's objects. The only list a buyer agent can read without a selection is its own granted advertisers. * A buyer agent cannot switch accounts. `X-SCOPE3-CUSTOMER-ID` on REST and the account-switch tools on MCP are refused for buyer agents. * Notification delivery re-checks the grant on every attempt, so revoking a grant also stops that advertiser's notifications reaching the agent. ## Review connections and readiness Open an agent from the **Agents** page. The console discovers the seller-account contexts already associated with that exact agent and organization and presents them by name. It never asks you to enter a numeric account ID. Choosing a named context grants nothing: the signed-in administrator must already be allowed to administer the organization, and the read remains isolated to that exact agent and seller account. The discovery response is available to directly authenticated organization administrators: ```bash theme={null} curl "$BASE/buyer-agent-principals//administration-contexts" \ -H "$AUTH" ``` It returns only the named contexts backed by current standing configuration for that principal. It does not expose or infer other organizations' accounts. The default experience translates configuration and readiness into customer language. It deliberately does not redisplay endpoint URLs, destination locations, recipient identities, extension data, proof artifacts, or credential material. Advanced diagnostics preserves official readback and proof state for support and engineering use. Use the principal administration read for one buyer agent and Seller Account: ```bash theme={null} curl "$BASE/buyer-agent-principals//administration?storefrontId=" \ -H "$AUTH" ``` `readback` preserves the four official AdCP states: `current`, `recognized`, `unconfigured`, or `failed`. A current response carries the exact configuration and version returned by `get_principal`. The authenticated API readback carries that configuration; the console renders only its safe summary. The supplemental `proof` section names each notification subscriber's explicit `pending`, `verified`, `failed`, or `stale` state. Reporting destinations are listed by generation and pattern with their recorded setup and proof states. Interchange does not infer proof success from a configured URL, destination, domain, credential, or prior result. If no recognized proof observation exists, `proofState` is `null`; absence or malformed evidence is not promoted to a state. Notification subscriber identifiers follow the official AdCP SDK limit of 64 characters. Both official configuration request schemas enforce that bound before a task handler runs, and the configuration service enforces it again before persistence. The administrative deactivation control retains the wider legacy storage-key range only so an unexpected pre-existing key can be disabled; it does not make that key valid configuration, identity, authority, or proof. The read returns every current destination plus the newest prior generations, up to 100 records total, and sets `reportingDestinationsTruncated` when older generations exist. Two histories stay separate: * `stateFeed` contains `principal.changed` transitions that require a fresh `get_principal` read. Seller-driven proof and destination-state changes are recorded there; your own successful `sync_principal` calls are not. The read returns the latest 100 and sets `stateFeedTruncated` when older transitions exist. The seller persists the transition and its stable logical notification together, so an interruption before webhook handoff is recovered without turning the webhook into state or authority. * `auditFeed` contains human administration changes and the exact authenticated person who made each change. It does not include endpoint URLs, destination locations, proof artifacts, or secrets. The read returns the latest 100 and sets `auditFeedTruncated` when older records exist. The readiness checklist reports five independent gates: registration, an active credential, current configuration with recorded proof, the exact advertised capability, and separate business authority. Every gate must be ready. A principal ID, credential, domain, destination, or proof result never satisfies the business-authority gate and never grants advertiser, account, spend, payment, or Terms access. These gates do not substitute for one another. SSO authenticates the person installing or administering the integration. A workload credential identifies the buyer agent. Only an explicit principal × advertiser or account grant can authorize business operations, and spend, payment, and Terms authority remain separate. The state screen can report those boundaries; it cannot create or approximate a missing grant. ## Stop a destination, subscriber, or principal Send an administration control to `POST /buyer-agent-principals//controls`. Every control requires `confirmationText` matching the buyer agent's stored display name exactly and a current state fence. A successful response is an applied receipt containing the resulting configuration version or lifecycle state; it does not depend on a second read after the control commits. Refresh the administration read separately to load the complete current view. * `deactivate_destination` requires `storefrontId`, `destinationId`, its exact `generation`, and `expectedConfigurationVersion`. * `deactivate_subscriber` requires `storefrontId`, `subscriberId`, and `expectedConfigurationVersion`. * `suspend` or `retire` applies to the agent as a whole and requires `expectedLifecycleState`. Use the agent-wide `lifecycle-controls` endpoint without a seller-account context. The original V2 `controls` request and receipt continue to require `storefrontId` for existing clients. Only a directly signed-in organization administrator can use these controls. Cross-organization or cross-principal targets, stale versions or generations, support and impersonated sessions, delegated or simulated sessions, API keys, OAuth clients, and ambiguous actor identity are refused. Configuration controls carry one five-second database deadline across authorization, state validation, and the committed mutation. The console exposes only controls backed by current contracts. Deactivating a destination or machine subscriber, pausing an agent, and retiring one all require you to retype the exact agent name. Configuration controls submit the reviewed version and, for a destination, its generation. Lifecycle controls submit the lifecycle state you reviewed, so a stale screen cannot silently change newer state. ## Issue a credential Send a new UUID idempotency key for this issuance. You may supply `replacesM2MSubject` only when replacing the directly preceding issued M2M credential for the same automation; Interchange verifies that lineage itself. ```bash theme={null} curl -X POST "$BASE/buyer-agent-principals/issue" \ -H "$AUTH" -H 'Content-Type: application/json' \ -d '{"displayName":"Reporting automation","idempotencyKey":""}' ``` Save `credential.clientSecret` immediately in your secret manager. It is shown once and cannot be retrieved, regenerated, or returned by a retry. The returned client ID is the automation's identity; it has no action permissions. It can authenticate but receives `403` from business APIs, including advertiser, account, spend, payment, Terms, and MCP operations. ## Reconcile an interrupted issuance If issuance reports `ISSUANCE_RECONCILIATION_REQUIRED`, repeat the **same** request with the same idempotency key after the transient failure has cleared. Interchange locks the durable issuance record, proves that no registry binding exists for its recorded client ID, discovers the deterministically named WorkOS application, and only then compensates it. A completed or otherwise uncertain binding is never deleted automatically. Do not create another request or use a new idempotency key until that retry has settled. If it reports that reconciliation is still required, retain the request ID and contact support; do not assume the client is active or delete it through the generic M2M endpoints. ## Rotate a credential ### API key Rotate a registered API key with only its current token ID. The server creates the successor with the same customer, organization, workload identity, and the next credential version; callers cannot provide a successor ID or lineage. ```bash theme={null} curl -X POST "$BASE/buyer-agent-principals/rotate" \ -H "$AUTH" -H 'Content-Type: application/json' \ -d '{"type":"api_key","currentServiceTokenId":"12345"}' ``` The response includes `credential.clientId` and `credential.clientSecret` once. Save both before deploying the successor. The previous key is retired only as part of the successful registry rotation. If the operation fails, do not create a manually linked replacement through `/service-tokens`; retry or contact support with the current token ID. ### WorkOS M2M To replace an issued WorkOS M2M subject while retaining its buyer-agent identity, issue the successor with `replacesM2MSubject`; the replacement is accepted only when the server-recorded workload lineage and direct predecessor match. This is a new-client rotation, not a generic M2M secret mutation. Identity-only applications are intentionally excluded from `/m2m-applications` list, secret, and delete operations so they cannot bypass direct WorkOS-admin authorization and registry audit. ## Revoke a credential To permanently stop an issued or registered credential from authenticating, use `POST /buyer-agent-principals/revoke`. Revocation is immediate and cannot be undone by registering the same credential again. If this was the buyer agent's last active credential, the principal becomes `suspended` and every call it makes is refused until you issue or register another credential for it. The `principal_id` is retained for audit, so the buyer agent's identity and history survive; only its ability to authenticate stops. ```bash theme={null} curl -X POST "$BASE/buyer-agent-principals/revoke" \ -H "$AUTH" -H 'Content-Type: application/json' \ -d '{"type":"workos_m2m","subject":""}' ``` For an API key, use `{ "type": "api_key", "serviceTokenId": "12345" }`.