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
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.
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.
The command groups are described in the following table. The API Reference lists the command group each operation belongs to.
|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.|
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.
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.
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.
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 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.
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.
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.