RoleService provides operations for creating and managing roles.

• Operations
• WSDL (sandbox)
• WSDL (production)
• About Roles
• Manage Roles

About Roles

To control access for your users, you can create custom roles that define a specific set of privileges. A privilege is a pre-defined grouping of capabilities and a role is a collection of privileges. Users are assigned roles that grant them the privileges defined in those roles. Privileges assigned to a role are cumulative, and can overlap. A user's privilege (granted via roles) dictates the user's level of access via the APIs.

For more information on roles, privileges, and capabilities, refer to Access and Licensing.

Manage Roles

RoleService provides operations for adding, updating, setting, retrieving, and deleting roles.

Add, Update, Retrieve, and Delete Roles

To create a custom role, use the addRole operation and to create a list of custom roles, use the addRoles operation.

To update a role, use the updateRole operation and to update a list of roles, use the updateRoles operation.

Note: If you add one or more privileges to an existing custom role, all the users who have been assigned that custom role will be granted the newly added privilege(s) via that role. If you remove a previlege from a custom role, all the users who have been assigned that custom role will lose that privilege.

To delete a role (specified by ID), use the deleteRole operation and to delete a list of roles (specified by IDs), use the deleteRoles operation.

Note: Before deleting a custom role, you must either assign any user with that custom role to another (standard or custom) role or disable any user with that role.

You must have AccountWrite capability (NetworkAdministrator role) to create, update, and delete custom roles.

To retrieve a role (specified by ID), use the getRole operation and to retrieve a list of roles (specified by IDs), use the getRoles operation. To retrieve a count of the roles for the account (in the request), use the getRoleCountByAccountID operation and to retrieve the custom roles for the account (in the request), use the getRolesByAccountID operation.

To retrieve the roles associated with an agency contract (specified by ID), use the getRolesByAgencyContractID operation.

Set and Retrieve Roles

To set a role (specified by ID) for one or more users (specified by IDs), use the setUsersForRole operation.

Note: You can assign many roles to a user.

You must have AccountWrite capability to assign and revoke roles assigned to a user.

To retrieve the users assigned to a role (specified by ID), use the getUsersForRole operation.

Retrieve Privileges

To retrieve a privilege (specified by ID), use the getPrivilege operation and to retrieve a list of privileges (specified by IDs), use the getPrivileges operation. To retrieve all the privileges, use the getAllPrivileges operation.

Retrieve Capabilities

To retrieve the capabilities associated with a privilege (specified by ID), use the getCapabilitiesForPrivilege operation and to retrieve the capabilities for a role (specified by ID), use the getCapabilitiesForRole operation.