{"_id":"56b7a85dd22adc0d0053f4c2","project":"569f9cf6650e1d1900f96b5b","githubsync":"","user":"5582e90181672a3900bb4fc7","__v":21,"category":{"_id":"56b25826147e900d00d6497a","project":"569f9cf6650e1d1900f96b5b","version":"569f9cf6650e1d1900f96b5e","pages":["56b2583a9621f20d00efb31c","56b25a3965ddf50d0076baa2","56b2738894ab060d0006743c","56b4d1cf5f1cf00d00cc46d7","56b4f4e2b1a8690d00a59369","56b4f6925f1cf00d00cc4704","56b4fa3d5997532100bc6bcc","56b50ba8eed075230097d71e","56b5123585a6922300d1c506","56b51e475997532100bc6c08","56b5220b7719bb1900143055","56b524cc3d5f130d00dad1b8","56b5265b168b5c1700c15996","56b774438fb4420d006a618b","56b78012eb783a0d007894f3","56b78292a6c10c0d00a2d65d","56b7863aeb783a0d007894f8","56b78f68a6c10c0d00a2d66b","56b794566c2a240d0094ae8a","56b7a85dd22adc0d0053f4c2","56b7ac118fb4420d006a61b7"],"__v":21,"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2016-02-03T19:42:30.051Z","from_sync":false,"order":7,"slug":"user-methods","title":"User methods"},"version":{"_id":"569f9cf6650e1d1900f96b5e","project":"569f9cf6650e1d1900f96b5b","__v":12,"createdAt":"2016-01-20T14:43:02.785Z","releaseDate":"2016-01-20T14:43:02.785Z","categories":["569f9cf7650e1d1900f96b5f","56abdd81d4432d1900eed235","56abe0558beeff0d003b8118","56ad2f8b1c09150d00a183a8","56ad4e1cd21f1b0d00fd2f97","56b00ad88f7a4f0d0029dc92","56b2432e9621f20d00efb2bd","56b25826147e900d00d6497a","56b7af2a4b372d2100722c48","56b8c4d938b1070d0028920f","56b8cdab14feef0d0082415d","58599813cf9e112d0032cdab"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"1.0.0","version":"1.0"},"parentDoc":null,"updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-02-07T20:26:05.273Z","link_external":false,"link_url":"","sync_unique":"","hidden":false,"api":{"examples":{"codes":[]},"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":21,"body":"## Syntax \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n    <credentials object>, \\n    \\\"user\\\": <mailbox_name>, \\n    \\\"role\\\": \\\"role_name\\\", \\n    \\\"object\\\": \\\"admin_object\\\"\\n}\",\n      \"language\": \"perl\",\n      \"name\": \"  \"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Request fields for set_role\"\n}\n[/block]\nThe following fields can be used in the **set_role** method:\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Field name\",\n    \"h-1\": \"Obligation\",\n    \"h-2\": \"Definition/Value\",\n    \"0-0\": \"object\",\n    \"0-1\": \"Required\",\n    \"0-2\": \"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.\",\n    \"1-0\": \"role\",\n    \"1-1\": \"Required\",\n    \"1-2\": \"The name of the role.\\n\\nAllowed values are: **company, company_mail, company_ro, company_token_only, company_view, domain, mail**, and **workgroup**.\\n\\n  * **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. \\n\\n  * **company_mail**—Can view and edit non- billable mailbox settings, cannot create or delete mailboxes or edit domain settings \\n\\n  * **company_ro**—Can view everything that a company administrator can, but does not have the ability to make changes.\\n\\n  * **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.\\n\\n  * **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.\\n\\n  * **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.\\n\\n  * **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.\\n\\n  * **workgroup**—Creates, deletes, and manages mailboxes within any workgroups for which they are administrators. \\n\\nTo remove a role, pass **null** or \\\"\\\" (empty string) for the role name.\",\n    \"2-0\": \"user\",\n    \"2-1\": \"Required\",\n    \"2-2\": \"The user to whom you are assigning a role.\"\n  },\n  \"cols\": 3,\n  \"rows\": 3\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Response fields for set_role\"\n}\n[/block]\nThe following fields may be returned in response to the **set_role** method:\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Field name\",\n    \"h-1\": \"Obligation\",\n    \"h-2\": \"Description/Value\",\n    \"0-0\": \"error\",\n    \"0-1\": \"Returned if **success = false**\",\n    \"0-2\": \"A text string that explains the error.\",\n    \"1-0\": \"error_number\",\n    \"1-1\": \"Returned if **success = false**\",\n    \"1-2\": \"A number that represents the error.\",\n    \"2-0\": \"success\",\n    \"2-1\": \"Always returned.\",\n    \"2-2\": \"Indicates whether the request was successful or not. Allowed values are **true** and **false**.\"\n  },\n  \"cols\": 3,\n  \"rows\": 3\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Examples for set_role\"\n}\n[/block]\nThis example make user mrmanager:::at:::example.com a workgroup admin of the workgroup sales.\n\n**Request 1**\n\nExample of setting a domain administrator for management of multiple domains: \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"credentials\\\": {\\n\\\"user\\\": \\\"company_admin@resellerusername.adm\\\",\\n    \\\"password\\\": \\\"password\\\"\\n  },\\n  \\\"user\\\": \\\"domain_admin@customerdomain1.com\\\",\\n  \\\"role\\\": \\\"domain\\\",\\n  \\\"objects\\\": [\\\"customerdomain1.com\\\",\\\"customerdomain2.com\\\"]\\n}\",\n      \"language\": \"perl\",\n      \"name\": \"  \"\n    }\n  ]\n}\n[/block]\n**Response 1** \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n\\t\\\"success\\\": true,\\n\\t\\\"audit\\\": \\\"month72_56b3b161b\\\"\\n}\",\n      \"language\": \"perl\"\n    }\n  ]\n}\n[/block]\n**Request 2**\n\nExample of setting a domain administrator for management of a single domain:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"credentials\\\": {\\n\\\"user\\\": \\\"company_admin@resellerusername.adm\\\",\\n    \\\"password\\\": \\\"password\\\"\\n  },\\n  \\\"user\\\": \\\"domain_admin@customerdomain1.com\\\",\\n  \\\"role\\\": \\\"domain\\\",\\n  \\\"object\\\": \\\"customerdomain1.com\\\"\\n}\\n\",\n      \"language\": \"perl\",\n      \"name\": \"  \"\n    }\n  ]\n}\n[/block]\n**Response 2**\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n\\t\\\"success\\\": true,\\n\\t\\\"audit\\\": \\\"month72_56b3b161b\\\"\\n}\",\n      \"language\": \"perl\",\n      \"name\": \"  \"\n    }\n  ]\n}\n[/block]","excerpt":"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.","slug":"set_role","type":"basic","title":"set_role"}

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 [block:code] { "codes": [ { "code": "{\n <credentials object>, \n \"user\": <mailbox_name>, \n \"role\": \"role_name\", \n \"object\": \"admin_object\"\n}", "language": "perl", "name": " " } ] } [/block] [block:api-header] { "type": "basic", "title": "Request fields for set_role" } [/block] The following fields can be used in the **set_role** method: [block:parameters] { "data": { "h-0": "Field name", "h-1": "Obligation", "h-2": "Definition/Value", "0-0": "object", "0-1": "Required", "0-2": "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.", "1-0": "role", "1-1": "Required", "1-2": "The name of the role.\n\nAllowed values are: **company, company_mail, company_ro, company_token_only, company_view, domain, mail**, and **workgroup**.\n\n * **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. \n\n * **company_mail**—Can view and edit non- billable mailbox settings, cannot create or delete mailboxes or edit domain settings \n\n * **company_ro**—Can view everything that a company administrator can, but does not have the ability to make changes.\n\n * **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.\n\n * **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.\n\n * **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.\n\n * **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.\n\n * **workgroup**—Creates, deletes, and manages mailboxes within any workgroups for which they are administrators. \n\nTo remove a role, pass **null** or \"\" (empty string) for the role name.", "2-0": "user", "2-1": "Required", "2-2": "The user to whom you are assigning a role." }, "cols": 3, "rows": 3 } [/block] [block:api-header] { "type": "basic", "title": "Response fields for set_role" } [/block] The following fields may be returned in response to the **set_role** method: [block:parameters] { "data": { "h-0": "Field name", "h-1": "Obligation", "h-2": "Description/Value", "0-0": "error", "0-1": "Returned if **success = false**", "0-2": "A text string that explains the error.", "1-0": "error_number", "1-1": "Returned if **success = false**", "1-2": "A number that represents the error.", "2-0": "success", "2-1": "Always returned.", "2-2": "Indicates whether the request was successful or not. Allowed values are **true** and **false**." }, "cols": 3, "rows": 3 } [/block] [block:api-header] { "type": "basic", "title": "Examples for set_role" } [/block] This example make user mrmanager@example.com a workgroup admin of the workgroup sales. **Request 1** Example of setting a domain administrator for management of multiple domains: [block:code] { "codes": [ { "code": "{\n \"credentials\": {\n\"user\": \"company_admin@resellerusername.adm\",\n \"password\": \"password\"\n },\n \"user\": \"domain_admin@customerdomain1.com\",\n \"role\": \"domain\",\n \"objects\": [\"customerdomain1.com\",\"customerdomain2.com\"]\n}", "language": "perl", "name": " " } ] } [/block] **Response 1** [block:code] { "codes": [ { "code": "{\n\t\"success\": true,\n\t\"audit\": \"month72_56b3b161b\"\n}", "language": "perl" } ] } [/block] **Request 2** Example of setting a domain administrator for management of a single domain: [block:code] { "codes": [ { "code": "{\n \"credentials\": {\n\"user\": \"company_admin@resellerusername.adm\",\n \"password\": \"password\"\n },\n \"user\": \"domain_admin@customerdomain1.com\",\n \"role\": \"domain\",\n \"object\": \"customerdomain1.com\"\n}\n", "language": "perl", "name": " " } ] } [/block] **Response 2** [block:code] { "codes": [ { "code": "{\n\t\"success\": true,\n\t\"audit\": \"month72_56b3b161b\"\n}", "language": "perl", "name": " " } ] } [/block]