set_role

The set_role method assigns a role to the specified user, removing any previous role. Roles give users administration rights over users, domains, and so on.

Syntax

{
    <credentials object>, 
    "user": <mailbox_name>, 
    "role": "role_name", 
    "object": "admin_object"
}

Request fields for set_role

The following fields can be used in the set_role method:

Field name

Obligation

Definition/Value

object

Required

The object over which the user will have administration rights. Companies, and domains are given by name. Workgroups are given as "domain/workgroup". A user must be a member of the object given. For example, a workgroup admin must be in the specified workgroup; a domain admin must be in the specified domain.

role

Required

The name of the role.

Allowed values are: company, company_mail, company_ro, company_token_only, company_view, domain, mail, and workgroup.

  • company—Performs all functions of a domain administrator in all domains within their company, and can edit their company information and suspend accounts. They can also add or remove domains and create and assign administrators, including company_mail, company_ro, and company_view admins.

  • company_mail—Can view and edit non- billable mailbox settings, cannot create or delete mailboxes or edit domain settings

  • company_ro—Can view everything that a company administrator can, but does not have the ability to make changes.

  • company_token_only—Can generate SSO tokens for users in any domains in their company. This is their only responsibility; they cannot view or change settings for domains or users.

  • company_view—Is similar to the company admin role except that the role does not have the ability to create or delete domains or mailboxes.

  • domain—Performs all functions of a workgroup administrator. In addition, can add/remove workgroups and workgroup administrators as well as manage and brand their domain.

  • mail—Manages mailboxes within the domain for which they are administrators. Typical tasks may be changing passwords, setting forwarding, adding or removing aliases, and setting auto responders.

  • workgroup—Creates, deletes, and manages mailboxes within any workgroups for which they are administrators.

To remove a role, pass null or "" (empty string) for the role name.

user

Required

The user to whom you are assigning a role.

Response fields for set_role

The following fields may be returned in response to the set_role method:

Field name

Obligation

Description/Value

error

Returned if success = false

A text string that explains the error.

error_number

Returned if success = false

A number that represents the error.

success

Always returned.

Indicates whether the request was successful or not. Allowed values are true and false.

Examples for set_role

This example make user [email protected] a workgroup admin of the workgroup sales.

Request 1

Example of setting a domain administrator for management of multiple domains:

{
  "credentials": {
"user": "[email protected]",
    "password": "password"
  },
  "user": "[email protected]",
  "role": "domain",
  "objects": ["customerdomain1.com","customerdomain2.com"]
}

Response 1

{
    "success": true,
    "audit": "month72_56b3b161b"
}

Request 2

Example of setting a domain administrator for management of a single domain:

{
  "credentials": {
"user": "[email protected]",
    "password": "password"
  },
  "user": "[email protected]",
  "role": "domain",
  "object": "customerdomain1.com"
}

Response 2

{
    "success": true,
    "audit": "month72_56b3b161b"
}