> ## 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. # List the organization's Interchange principals > Return the organization's operator principal and every buyer-agent principal it owns, with each buyer agent's safe credential facts and exact active advertiser access. A directly authenticated WorkOS organization administrator is required; impersonated, simulated, delegated, service-credential, advertiser-scoped, and cross-organization callers are refused. The organization boundary is derived from the authenticated context, never from the request. No credential secret is returned, and issuer URLs, WorkOS organization IDs, access client IDs, operator domains, brand.json/JWKS URLs, key IDs, and key fingerprints are credential facts that are never principal identity and are not returned here. Operator and buyer-agent principals are separate collections, and the operator carries no credentials, so no credential lifecycle action can be expressed against it. Registration and credential facts do not grant advertiser, account, spend, payment, or Terms access. ## OpenAPI ````yaml /v2/buyer-api-v2.yaml get /buyer-agent-principals openapi: 3.0.0 info: title: Scope3 Buyer API version: 2.0.0 description: |- REST API for advertisers to manage advertisers, campaigns, and reporting. ## Authentication All endpoints require a Bearer token in the Authorization header: ``` Authorization: Bearer your-api-key ``` ## Base URL `https://api.interchange.io/api/v2/buyer` ## For AI Agents AI agents can use the MCP endpoint at `/mcp/v2/buyer` with three tools: - `initialize`: Start an MCP session - `api_call`: Make REST API calls - `ask_about_capability`: Learn about API features servers: - url: https://api.interchange.io/api/v2/buyer description: Production server security: [] tags: - name: Signup description: Request reviewed access to Interchange - name: Account description: Account management, service tokens, and preferences - name: Asks description: >- What you are waiting on Scope3 for — support, product, and supply asks in one list - name: Advertisers description: Manage advertisers - name: Product Discovery description: Discover and select products - name: Campaigns description: Manage advertising campaigns - name: Creatives description: Build, manage, and sync campaign creatives via AdCP Creative Protocol - name: Reporting description: Access performance metrics - name: Event Sources description: >- Manage event source configurations and log conversion/marketing events for attribution - name: Property Lists description: Validate property lists against AAO registry - name: Sales Agents description: View and connect sales agents - name: Measurement description: Measurement sources, records, context, and freshness - name: Syndication description: Syndicate resources to ADCP agents - name: Tasks description: Track async operation status - name: Buyer Billing description: >- Consolidated invoicing for buyers — invoices and pending invoice items issued by Scope3 across the buyer customer. - name: MCP description: Model Context Protocol endpoints for AI agents paths: /buyer-agent-principals: servers: - url: https://api.interchange.io/api/v2 description: Production server get: tags: - Buyer Agent Principals summary: List the organization's Interchange principals description: >- Return the organization's operator principal and every buyer-agent principal it owns, with each buyer agent's safe credential facts and exact active advertiser access. A directly authenticated WorkOS organization administrator is required; impersonated, simulated, delegated, service-credential, advertiser-scoped, and cross-organization callers are refused. The organization boundary is derived from the authenticated context, never from the request. No credential secret is returned, and issuer URLs, WorkOS organization IDs, access client IDs, operator domains, brand.json/JWKS URLs, key IDs, and key fingerprints are credential facts that are never principal identity and are not returned here. Operator and buyer-agent principals are separate collections, and the operator carries no credentials, so no credential lifecycle action can be expressed against it. Registration and credential facts do not grant advertiser, account, spend, payment, or Terms access. operationId: listOrganizationPrincipals responses: '200': description: List the organization's Interchange principals content: application/json: schema: $ref: '#/components/schemas/OrganizationPrincipalsApiResponse' '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: >- The caller is not a directly authenticated WorkOS organization administrator, or the authenticated organization does not match this customer. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' security: - bearerAuth: [] components: schemas: OrganizationPrincipalsApiResponse: type: object properties: data: type: object properties: operator: nullable: true type: object properties: principalId: type: string pattern: ^prin_[A-Za-z0-9_-]{32}$ principalKind: type: string enum: - operator displayName: type: string lifecycleState: type: string enum: - active - suspended - retired registeredAt: type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ authority: type: object properties: advertiserAccountIds: type: array items: not: {} permissions: type: array items: not: {} required: - advertiserAccountIds - permissions additionalProperties: false deprecated: true description: >- Deprecated compatibility field; always structurally empty and scheduled for removal no earlier than 2027-09-07 at the next major API surface. Use access instead. required: - principalId - principalKind - displayName - lifecycleState - registeredAt - authority additionalProperties: false buyerAgents: type: array items: type: object properties: principalId: type: string pattern: ^prin_[A-Za-z0-9_-]{32}$ principalKind: type: string enum: - buyer_agent displayName: type: string lifecycleState: type: string enum: - active - suspended - retired registeredAt: type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ activeCredentialCount: type: integer minimum: 0 maximum: 9007199254740991 credentials: type: array items: type: object properties: credentialRef: type: string minLength: 1 credentialType: type: string enum: - workos_m2m - api_key - domain_rfc9421 bindingState: type: string enum: - active - retired administrationHandle: nullable: true oneOf: - type: object properties: type: type: string enum: - workos_m2m subject: type: string minLength: 1 required: - type - subject additionalProperties: false - type: object properties: type: type: string enum: - api_key serviceTokenId: type: string pattern: ^[1-9][0-9]{0,18}$ required: - type - serviceTokenId additionalProperties: false type: object boundAt: type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ lastVerifiedAt: type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ retiredAt: nullable: true type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ required: - credentialRef - credentialType - bindingState - administrationHandle - boundAt - lastVerifiedAt - retiredAt additionalProperties: false authority: type: object properties: advertiserAccountIds: type: array items: not: {} permissions: type: array items: not: {} required: - advertiserAccountIds - permissions additionalProperties: false deprecated: true description: >- Deprecated compatibility field; always structurally empty and scheduled for removal no earlier than 2027-09-07 at the next major API surface. Use access instead. access: type: object properties: accessRevision: type: integer minimum: 0 maximum: 9007199254740991 advertisers: type: array items: type: object properties: advertiserId: type: string pattern: ^[1-9][0-9]{0,18}$ name: type: string minLength: 1 role: type: string enum: - READ - READ_WRITE required: - advertiserId - name - role additionalProperties: false required: - accessRevision - advertisers additionalProperties: false required: - principalId - principalKind - displayName - lifecycleState - registeredAt - activeCredentialCount - credentials - authority - access additionalProperties: false required: - operator - buyerAgents additionalProperties: false error: type: string nullable: true enum: - null required: - data - error additionalProperties: false ErrorResponse: type: object properties: data: type: string nullable: true enum: - null error: $ref: '#/components/schemas/ApiError' required: - data - error additionalProperties: false description: Standard error response ApiError: type: object properties: code: type: string description: Machine-readable error code message: type: string description: Human-readable error message field: description: Field path associated with the error type: string details: description: Additional error context type: object additionalProperties: {} required: - code - message additionalProperties: false description: Structured error object securitySchemes: bearerAuth: type: http scheme: bearer description: API key or access token ````