Web Services includes authentication and authorization tiers that govern your access to the system, enforce your quota restrictions, and determine which operations you can perform.

• Licensing, Authentication, and Login
• Command Groups and Quotas
• Roles, Privileges, and Capabilities
• Command Groups and Quotas v. Roles, Privileges, and Capabilities
• Access Restrictions

Licensing, Authentication, and Login

When you enroll with Web Services, you obtain a license that includes your license key, command groups, and quota.

Your account management team will help you set up an initial username and password and create an initial account, which you can use as a starting point to use the platform.

Your license key, account ID, username, and password are a basic form of authentication and must be included in every Web Services request. You can also use the same username and password to log into the web application.

Command Groups and Quotas

In addition to the license key, your Web Services license specifies the command groups you have access to and the quota you have been granted.

A command group is a set of one or more operations. Quota is the total number of requests you can make in a 24-hour period using any of the operations in a command group. Your command groups and quota may vary depending on whether you are using the sandbox or the production system.

Command Groups

The command groups are described in the following table. The API Reference lists the command group each operation belongs to.

Command Group	Description
AccountManagement	A set of operation for managing accounts.
Creatives	A set of operations for managing creatives and ads.
CreativeUpload	A set of operations for adding creatives and templates.
Inventory	A set of operations for managing inventory.
NetworkManagement	A set of operations for creating and managing users, links, filters, pixels, and approvals, and retrieving targeting information.
Orders	A set of operations for creating and managing orders.
Reports	A set of operations for managing reports.

Quotas

Each Web Services request includes either an operation or list-based operation that counts against your quota (see Tracking Quota for Web Services requests). For list-based operations that process multiple objects, quota is charged for each item in the list.

Each Web Services response includes elements in the SOAP header that show the command group to which the operation belongs and the remaining quota for that command group. You can use this information to track your quota consumption and to manage your Web Services requests (see Tracking Quota for Web Services responses).

When you exceed your quota for any command group, additional Web Services requests are rejected with a Quota Exceeded SOAP fault. Your quota is reset at midnight in the time zone of the license holder account.

To determine the quota usage information, use the LicenseService.getQuotaUsage method.

Roles, Privileges, and Capabilities

Your Web Services license specifies your command groups and quota. Which operations you can actually perform, however, is based on the roles, privileges, and capabilities that are assigned to you.

A role is a collection of privileges. A privilege is a set of capabilities. A capability is a set of tasks a user can perform. In short, a role is a simple way to grant one or more privileges (and associated capabilities) to a user.

Roles

A role is assigned to a user in the context of an account. When you enroll with Web Services, the initial username is granted the role of Network Administrator for the initial account. The Network Administrator has full access to the account and has access to all accounts managed by the network account. The Network Administrator also has all the necessary privileges (and associated capabilities) to create, update, and remove roles.

Privileges

A privilege is permission or right granted to a user to an application capability. You can grant one or more of the privileges through roles. You can retrieve the supported list of privileges using the getAllPrivileges method.

Capabilities

Capabilities are related to product areas and map to specific operations. For example, the SiteWrite capability includes those operations that allow you to add, update, and delete sites, sections, and custom content categories. The SiteRead capability include those operations that allow you to get information about sites, sections, and custom content categories.

The API Reference lists the required capability for each operation. You can also retrieve the capabilities for each role using the getCapabilitiesForRole method. The various capabilities associated with each privilege can also be retrieved using the getCapabilitiesForPrivilege method. Before assigning roles to users, ensure that the role has the necessary privileges (and associated capabilities) to perform the necessary tasks (operations).

CompositeAccountWrite Capability: The CompositeAccountWrite capability maps the underlying account write capability to the account type in the header. For account write operations that can be performed by multiple account types, such as the setBillingProfile operation in AccountService, the CompositeAccountWrite capability is used to map the account type (in the header) to the corresponding account write capability. For example, if the account type in the header is:

• ManagedAgency, the capability required for a method annotated with CompositeAccountWrite would be ManagedAgencyAccountWrite capability.
• ManagedAdvertiser, the capability required for a method annotated with CompositeAccountWrite would be ManagedAdvertiserAccountWrite capability.
• ManagedPublisher, the capability required for a method annotated with CompositeAccountWrite would be ManagedPublisherAccountWrite capability.

Command Groups and Quotas v. Roles, Privileges, and Capabilities

Keep in mind that command groups and quotas are distinct from roles, privileges, and capabilities. Command groups and quotas determine which operations you can perform, and how often you can perform them. Roles, privileges, and capabilities determine which users can perform specific operations and tasks.

For example, an account's license may grant a quota of 10,000 calls for the operations in a particular command group; however, if the username included in the Web Services request does not have the right role, privilege, and capability for the specified operation, the request will fail.

Conversely, the username in the Web Services request may have the correct role, privilege, and capability for the operation in question; however, if the company’s license does not grant any quota for the command group the operation belongs to, the request will fail.

Access Restrictions

Your account type determines the services (and operations) that you have access to. Review the following table to determine the services (and operations within) that you can access via the API.

Creative Services Creative Services This service... Can be accessed by... CustomizableFlashCreativeService Managed advertiser, self-managed account with advertiser capability CustomizableFlashTemplateService Managed advertiser, self-managed account with advertiser capability EditorialService Managed advertiser, self-managed account with advertiser capability FlashCreativeService Managed advertiser, self-managed account with advertiser capability FolderService Managed advertiser, self-managed account with advertiser capability ImageCreativeService Managed advertiser, self-managed account with advertiser capability LibraryAdInformationService Managed advertiser, self-managed account with advertiser capability LibraryAdTemplateService Self-managed account with publisher capability, self-managed account with managed publishers LibraryBumperVideoAdService Managed advertiser, self-managed account with advertiser capability LibraryClickableVideoAdService Managed advertiser, self-managed account with advertiser capability LibraryClickToSiteOverlayVideoAdService Managed advertiser, self-managed account with advertiser capability LibraryClickToVideoOverlayVideoAdService Managed advertiser, self-managed account with advertiser capability LibraryCustomHTMLAdService Managed advertiser, self-managed account with advertiser capability LibraryCustomizableFlashAdService Managed advertiser, self-managed account with advertiser capability LibraryFlashAdService Managed advertiser, self-managed account with advertiser capability LibraryImageAdService Managed advertiser, self-managed account with advertiser capability LibraryInteractiveFourStageVideoAdService Managed advertiser, self-managed account with advertiser capability LibraryThirdPartyAdService Managed advertisers, self-managed account with advertiser capability VideoCreativeService Managed advertiser, self-managed account with advertiser capability
InventoryServices Inventory Services This service... Can be accessed by... AdDeliveryModeService Self-managed account with managed publishers, self-managed account with publisher capability AdMarkerService Self-managed account with managed publishers, self-managed account with publisher capability AdTagService Managed publisher, self-managed account with managed publishers AudienceSegmentCategoryService Self-managed account with managed publishers, self-managed account with publisher capability AudienceSharingRulesService Self-managed account with managed publishers, self-managed account with publisher capability BookingLimitService Self-managed account with managed publishers, self-managed account with publisher capability CustomGeoAreaService Self-managed account with managed publishers, self-managed account with publisher capability InventoryContributionRuleService Self-managed account with Publisher capability, self-managed account with managed publishers InventoryForecastAdjustmentService Self-managed account with Publisher capability, self-managed account with managed publishers InventoryIdentifierService Managed publisher, self-managed account with publisher capability InventoryOptInService Self-managed account with Publisher capability, self-managed account with managed publishers InventoryPackagePlacementService Self-managed account with Publisher capability, self-managed account with managed publishers InventoryPackageService Self-managed account with Publisher capability, self-managed account with managed publishers PaletteService Managed publisher, self-managed account with publisher capability PartnerRulesService Self-managed account with Publisher capability, self-managed account with managed publishers PublisherCustomDataService Managed publisher, self-managed account with publisher capability RateCardService Managed publisher, self-managed account with publisher capability, any self-managed account RateTagService Managed publisher, self-managed account with publisher capability ReferralSegmentService Self-managed account with Publisher capability, self-managed account with managed publishers ReportingTagService Managed publisher, self-managed account with publisher capability SiteClassificationService Managed publisher, self-managed account with publisher capability SiteService Managed publisher, self-managed account with publisher capability TargetingRuleService Self-managed account with Publisher capability, self-managed account with managed publishers
Network Services Network Services This service... Can be accessed by... AccountService Any self-managed account AdjustmentService Any self-managed account ApprovalService Any self-managed account ApprovalTaskService Any self-managed account ApprovalWorkflowService Any self-managed account AttributeTypeService Any account CommonTargetingService Any account ContactService Any managed account CostFeedService Any account FilterService Any self-managed account GeographicalTargetingService Any account License Any self-managed account LinkingProfileService Any self-managed account LinkingService Any self-managed account LocationService Any account OrderNetworkAttributeService Any account PixelService Any account ReportService Any account RoleService Any self-managed account StandardAttributeService Any account TargetingDictionaryService Any account UploadService Any account UserService Any self-managed account
Order Services Order Services This service... Can be accessed by... AdService Managed advertisers, self-managed account with advertiser capability ExperimentService Managed advertiser, self-managed account with advertiser capability InventorySearchService Managed advertiser, self-managed account with advertiser capability OrderService Managed advertiser, self-managed account with advertiser capability PlacementService Managed advertiser, self-managed account with advertiser capability TargetingProfileService Managed advertiser, self-managed account with advertiser capability TestGroupService Managed advertiser, self-managed account with advertiser capability