Skip to main content
A Principal represents a distinct client or buyer in AdCP. Sales agents use principals to identify who is making requests and enforce data isolation between different buyers.

​
Authentication

All requests must be authenticated using a bearer token in the standard Authorization header: 
Authorization: Bearer <your_token>
The server validates this token and associates it with a specific principal_id. All subsequent operations within that request are scoped to that authenticated principal. See Authentication for details on obtaining credentials and authentication methods.

​
The Principal Model

A Principal is defined by:
  • principal_id (string): A unique identifier for the client (e.g., "acme_corp").
  • platform_mappings (object): Maps the principal_id to identifiers in ad serving platforms (e.g., {"gam_advertiser_id": 12345}).

​
Data Isolation

Authentication provides the foundation for strict data isolation. Sales agents MUST enforce the following rules:
  1. When an object like a MediaBuy is created, it MUST be permanently associated with the principal_id from the authenticated request context.
  2. For any subsequent request to read or modify that object, the server MUST verify that the principal_id from the request matches the principal_id stored with the object.
  3. If the IDs do not match, the server MUST return a permission denied error.
This model ensures that one principal can never view or modify another principal’s data, as they will not possess the correct bearer token to do so. Passing a principal_id in the request body is not required or respected; the identity is based solely on the validated token.

​
Security Requirements

​
Required Security Measures

Sales agent implementations MUST:
  • Validate bearer tokens on every authenticated request
  • Enforce principal-based data isolation
  • Use TLS for all communications
  • Log authentication failures for security monitoring
Sales agent implementations SHOULD:
  • Implement rate limiting per principal
  • Support token expiration and refresh
  • Provide audit logging for compliance
  • Support IP allowlisting for high-security principals