Admin permissions
Admin permissions allow for fine-grained control over what Teamwire admins are allowed to do in their organisation.
Manage Teamwire admin permissions
Return an admin’s permissions
GET /v<api_version>/admin/adminpermissions/<admin_email_hash>/
Access restrictions
- Admins and Superadmins can call this endpoint with their own admin_email_hash to obtain information about their own permissions.
- Calling this endpoint with an admin_email_hash of another admin requires the allow_view_admins permission.
- Calling this endpoint with an admin_email_hash of an admin in a different organisation requires being Superadmin.
URL parameters
The following parameters are specified as part of the URL, i.e. /<parameter>/:
| Name | Type | Optional | For use by | Description |
|---|---|---|---|---|
| api_version | String | No | All admins | The Enterprise API version targeted. |
| admin_email_hash | String | No | All admins | The hashed email address of a particular admin for whom permissions should be returned. |
Result
The following return values indicate the outcome of the API call:
| HTTP status code | Description |
|---|---|
| 200 (OK) | The request was successful. Admin permissions will be returned as a JSON object as described below. |
| 401 (Unauthorized) | The request failed because the caller failed to first login to the Enterprise API or her session expired. Login to obtain a new session and repeat the request. |
| 403 (Forbidden) | The request failed because either a.) the calling admin’s organisation has been |
disabled or b.) the calling admin is not the specified admin and she does not have the allow_view_admins permission or c.) the specified admin also belongs to a different organisation and the calling admin is not a Superadmin. |
|
| 404 (Not Found) | The request failed because the specified admin could not be found. |
| 409 (Conflict) | The request failed because the organisation the specified admin belongs to has been disabled. |
If the request was successful, a single JSON object is returned with the following elements:
| Name | Type | Visible to | Description |
|---|---|---|---|
| admin_email_hash | String | All admins | The admin’s email address in a hashed format. |
| allow_view_users | Boolean | All admins | Whether the admin may use the API to view users. |
| allow_modify_users | Boolean | All admins | Whether the admin may use the API to modify users. |
| allow_view_groups | Boolean | All admins | Whether the admin may use the API to view groups. |
| allow_modify_groups | Boolean | All admins | Whether the admin may use the API to modify groups. |
| allow_view_api_keys | Boolean | All admins | Whether the admin may use the API to view API keys. |
| allow_modifu_api_keys | Boolean | All admins | Whether the admin may use the API to modify API keys. |
| allow_view_admins | Boolean | All admins | Whether the admin may use the API to view admins. |
| allow_modify_admins | Boolean | All admins | Whether the admin may use the API to modify admins. |
| allow_view_domains | Boolean | All admins | Whether the admin may use the API to view domains. |
| allow_modify_domains | Boolean | All admins | Whether the admin may use the API to modify domains. |
| allow_view_settings | Boolean | All admins | Whether the admin may use the API to view settings. |
| allow_modify_settings | Boolean | All admins | Whether the admin may use the API to modify settings. |
| allow_manage_ldap_sync | Boolean | All admins | Whether the admin may use the API to manage the LDAP sync process. |
| allow_view_audit_log | Boolean | All admins | Whether the admin may use the API to view the audit log. |
Set admin permissions
PUT /v<api_version>/admin/adminpermissions/<admin_email_hash>/
Access restrictions
- Admins and Superadmins can not call this endpoint with their own admin_email_hash as permissions can only be set by other admins.
- Calling this endpoint with an admin_email_hash of an admin in a different organisation requires being Superadmin.
- Admins and Superadmins must have the allow_modify_admins permission.
- Admins and Superadmins can only modify permissions they own themselves in order to prevent
- a cooperating admin A from helping a malicious admin B gain additional permissions
- a malicious admin A from taking away admin B’s additional permissions
URL parameters
The following parameters are specified as part of the URL, i.e. /<parameter>/:
| Name | Type | Optional | For use by | Description |
|---|---|---|---|---|
| api_version | String | No | All admins | The Enterprise API version targeted. |
| admin_email_hash | String | No | All admins | The hashed email address of a particular admin for whom permissions are to be set. |
PUT data
Parameters are supplied as a JSON object with the following elements:
| Name | Type | Optional | Description |
|---|---|---|---|
| allow_view_users | Boolean | Yes | Whether the admin may use the API to view users. |
| allow_modify_users | Boolean | Yes | Whether the admin may use the API to modify users. |
| allow_view_groups | Boolean | Yes | Whether the admin may use the API to view groups. |
| allow_modify_groups | Boolean | Yes | Whether the admin may use the API to modify groups. |
| allow_view_api_keys | Boolean | Yes | Whether the admin may use the API to view API keys. |
| allow_modify_api_keys | Boolean | Yes | Whether the admin may use the API to modify API keys. |
| allow_view_admins | Boolean | Yes | Whether the admin may use the API to view admins. |
| allow_modify_admins | Boolean | Yes | Whether the admin may use the API to modify admins. |
| allow_view_domains | Boolean | Yes | Whether the admin may use the API to view domains. |
| allow_modify_domains | Boolean | Yes | Whether the admin may use the API to modify domains. |
| allow_view_settings | Boolean | Yes | Whether the admin may use the API to view settings. |
| allow_modify_settings | Boolean | Yes | Whether the admin may use the API to modify settings. |
| allow_manage_ldap_sync | Boolean | Yes | Whether the admin may use the API to manage the LDAP sync process. |
| allow_view_audit_log | Boolean | Yes | Whether the admin may use the API to view the audit log. |
Result
The following return values indicate the outcome of the API call:
| HTTP status code | Description |
|---|---|
| 200 (OK) | The request was successful. The updated admin permissions will be returned as a JSON object as described for the GET request. |
| 401 (Unauthorized) | The request failed because the caller failed to first login to the Enterprise API or her session expired. Login to obtain a new session and repeat the request. |
| 403 (Forbidden) | The request failed because either a.) the calling admin’s organisation has been disabled, b.) the calling admin is not a Superadmin and an admin was specified that does not belong to the calling admin’s organisation, c.) the calling admin doesn’t possess the “Allow modify admins” permission or d.) an attempt was made to assign permissions which the calling admins doesn’t own herself. |
| 404 (Not Found) | The request failed because the admin whose permissions are to be modified could not be found. |
| 409 (Conflict) | The request failed because the organisation the admin whose permissions are to be modified belongs to has been disabled. |