Admins
A Teamwire administrator represents an individual human or application with access to the Dashboard. Administrator accounts exist independently from user accounts.
While the first admin to register will be automatically active, successive admins register on their own will need to be confirmed by existing admins.
Admins can have different privilege levels: ordinary admins are limited to operations on their own organisation and may in addition have been limited in their access. Only Superadmins can operate on other organisations.
Admin account confirmation
Confirm an admin registration
POST /v<api_version>/admin/admins/<auth>/confirm_account/
Calling this endpoint completes the new admin’s registration and allows her to log in to the Enterprise API.
Access restrictions
- Admins and Superadmins must have the allow_modify_admins permission.
- Admins can confirm admin registrations in their own organisation only.
- Superadmins can confirm admin registrations in any organisation.
- The confirmed admin will inherit permissions from the confirming Admin/Superadmin. Thus care should be taken in determining who gets to confirm a new admin account: the new admin will only be “fully-featured” if the confirming admin herself has the desired permissions. This is to prevent restricted admins from registering and confirming a new admin account in order to circumvent their own restrictions.
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. |
| auth | String | No | All admins | An authorization code identifying a particular admin registration. This code is usually received via Email. |
Result
The following return values indicate the outcome of the API call:
| HTTP status code | Description |
|---|---|
| 200 (OK) | The request was successful. Information on the new admin is 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 b.) the calling admin is not a Superadmin and the admin to confirm would not belong to the calling admin’s organisation or c.) the authorization information contained an invalid secret. |
| 404 (Not found) | The request failed because no matching admin registration could be found. |
| 409 (Conflict) | The request failed because either a.) the admin registration has already been confirmed or the b.) the organisation the new admin would belong to has been disabled. |
Get admin confirmation data
GET /v<api_version>/admin/admins/<auth>/confirm_account/
This endpoint returns the data of the new admin registration in order to be presented to and checked by an existing admin.
Access restrictions
- Admins and Superadmins must have the allow_view_admins permission.
- Admins can view admin registrations in their own organisation only.
- Superadmins can view admin registrations in any organisation.
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. |
| auth | String | No | All admins | An authorization code identifying a particular admin registration. This code is usually received via Email. |
Result
The following return values indicate the outcome of the API call:
| HTTP status code | Description |
|---|---|
| 200 (OK) | The request was successful. Information on the status of the admin’s confirmation is 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, b.) the calling admin is not a Superadmin and the admin to return confirmation data for would not belong to the calling admin’s organisation or c.) the authorization information contained an invalid secret. |
| 404 (Not found) | The request failed because no matching admin registration could be found. |
| 409 (Conflict) | The request failed because either a.) the admin registration has already been confirmed or the b.) the organisation the new admin would belong to has been disabled. |
Manage Teamwire admins
Create a new admin account
POST /v<api_version>/admin/admins/
Access restrictions
- Admins and Superadmins must have the allow_modify_admins permission.
- Admins can create admins in their own organisation only.
- Superadmins can create admins in any organisation.
- The new admin account will be created with permissions inherited from the creating Admin/Superadmin. Thus care should be taken in determining who gets to create a new admin account: a new “fully-featured” admin can only by created by an admin who owns the desired permissions herself. This is to prevent restricted admins from circumventing their own missing permissions by creating a new account.
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. |
POST data
Parameters are supplied as a JSON object with the following elements:
| Name | Type | Optional | For use by | Description |
|---|---|---|---|---|
first_name |
String | No | All admins | The admin’s first name. |
last_name |
String | No | All admins | The admin’s last name. |
email |
String | No | All admins | The admin’s email address. |
mobile |
String | No | All admins | The admin’s mobile phone number. |
phone |
String | No | All admins | The admin’s phone number. |
company |
String | No | All admins | The admin’s company. |
role |
String | No | All admins | The admin’s role. |
division |
String | No | All admins | The admin’s division. |
postcode |
String | No | All admins | The admin’s post code. |
city |
String | No | All admins | The admin’s city. |
address |
String | No | All admins | The admin’s address. |
country |
String | No | All admins | The admin’s country. |
super_admin |
Boolean | Yes | Superadmins | Whether the admin should have Superadmin privileges. |
Result
The following return values indicate the outcome of the API call:
| HTTP status code | Description |
|---|---|
| 200 (OK) | The request was successful. Information about the created admin is returned as a JSON object as described for the GET request. |
| 400 (Bad request) | The request failed because an admin with the supplied email address already exists. |
| 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 tried to add a Superadmin or c.) the calling admin is not a Superadmin and tried to create an admin with an email address that belongs to a different organisation. |
| 409 (Conflict) | The request failed because the organisation the created admin would belong to has been disabled. |
Return a list of admins or details about a particular admin
GET /v<api_version>/admin/admins/
GET /v<api_version>/admin/admins/<admin_email_hash>/
Access restrictions
- Admins and Superadmins must have the allow_view_admins permission.
- Admins can request details of admins in their own organisation only.
- Superadmins can request details of admins in any organisation.
- If no admin_email_hash is specified:
- admins will receive a list of admins in their own organisation only.
- Superadmins a list of admins in all organisations.
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 | Yes | All admins | The hashed email address of a particular admin for which details should be returned. It can be obtained by first requesting a list of all admins. |
Result
The following return values indicate the outcome of the API call:
| HTTP status code | Description |
|---|---|
| 200 (OK) | The request was successful. Admin information is 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 a Superadmin and an admin was specified that does not belong to the calling admin’s organisation. |
| 404 (Not Found) | The request failed because the specified admin could not be found. |
| 409 (Conflict) | The request failed because the organisation the admin belongs to has been disabled. |
If no hashed email address was specified and the request was successful, the JSON structure returned is an array of JSON objects with the following elements:
| Name | Type | Visible to | Description |
|---|---|---|---|
first_name |
String | All admins | The admin’s first name. |
last_name |
String | All admins | The admin’s last name. |
email |
String | All admins | The aAmin’s email address. |
email_hash |
String | All admins | The admin’s email address in a hashed format. |
organisation_id |
String | All admins | The ID of the admin’s organisation. |
created_at |
String | All admins | When the admin was created. A combined date/time in JavaScript’s standard ISO 8601-conforming format and with UTC as time zone will be returned, i.e. “DDDD-MM-YYYY’T’HH:MM:SS.SSS’Z’“, for example “2019-03-19T13:41:11.257Z”. |
last_login |
Number | All admins | When the admin last logged on. A timestamp in seconds since 1970-01-01 00:00:00 UTC will be returned. |
enabled |
Boolean | All admins | Whether the admin is enabled or not. A disabled admin will be unable to perform actions against the Enterprise API. |
super_admin |
Boolean | All admins | Whether the admin has Superadmin privileges. |
two_factor_enabled |
Boolean | All admins | Whether the admin has enabled two-factor authentication (2FA). |
If a hashed email address was specified and the request was successful, a single JSON object is returned with elements as above plus the following additional elements:
| Name | Type | Visible to | Description |
|---|---|---|---|
mobile |
String | All admins | The admin’s mobile phone number. |
phone |
String | All admins | The admin’s phone number. |
company |
String | All admins | The admin’s company. |
role |
String | All admins | The admin’s role. |
division |
String | All admins | The admin’s division. |
postcode |
String | All admins | The admin’s post code. |
city |
String | All admins | The admin’s city. |
address |
String | All admins | The admin’s address. |
country |
String | All admins | The admin’s country. |
preferred_language |
String | All admins | The admin’s preferred language. This is for consideration by applications using the Enterprise API. |
Update an existing admin
PUT /v<api_version>/admin/admins/<admin_email_hash>/
Access restrictions
- Admins and Superadmins must have the allow_modify_admins permission.
- Admins can update admins in their own organisation only.
- Superadmins can update admins in any organisation.
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 the admin to be updated. The special keyword “self” must be used when the calling admin wants to update her own account. |
PUT data
Parameters are supplied as a JSON object with the following elements:
| Name | Type | Optional | For use by | Description |
|---|---|---|---|---|
first_name |
String | No | All admins | The admin’s new first name. |
last_name |
String | No | All admins | The admin’s new last name. |
mobile |
String | No | All admins | The admin’s new mobile phone number. |
phone |
String | No | All admins | The admin’s new phone number. |
company |
String | No | All admins | The admin’s new company. |
role |
String | No | All admins | The admin’s new role. |
division |
String | No | All admins | The admin’s new division. |
postcode |
String | No | All admins | The admin’s new post code. |
city |
String | No | All admins | The admin’s new city. |
address |
String | No | All admins | The admin’s new address. |
country |
String | No | All admins | The admin’s new country. |
enabled |
Boolean | No | All admins | Whether the admin should be enabled or not. A disabled admin will be unable to perform actions against the Enterprise API. |
super_admin |
Boolean | No | Superadmins | Whether the admin should have Superadmin privileges. |
preferred_language |
String | No | All admins | The admin’s new preferred language. This is for consideration by applications using the Enterprise API. |
Result
The following return values indicate the outcome of the API call:
| HTTP status code | Description |
|---|---|
| 200 (OK) | The request was successful, the admin has been updated. Updated admin information is 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 limited to read-only access, c.) the calling admin attempted to update her own account without using the special keyword “self” or d.) the calling admin is not a Superadmin and attempted to update an admin that does not belong to her organisation. |
| 404 (Not Found) | The request failed because the admin to be updated could not be found. |
| 409 (Conflict) | The request failed because the organisation the admin to be updated belongs to has been disabled. |
Delete an admin
DELETE /v<api_version>/admin/admins/<admin_email_hash>/
Access restrictions
- Admins and Superadmins must have the allow_modify_admins permission.
- Admins can delete admins in their own organisation only.
- Superadmins can delete admins in any organisation.
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 the admin to be deleted. |
Result
The following return values indicate the outcome of the API call:
| HTTP status code | Description |
|---|---|
| 200 (OK) | The request was successful. The admin has been deleted. |
| 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 tried to delete herself or c.) the calling admin is not a Superadmin and the admin to delete does not belong to the calling admin’s organisation. |
| 404 (Not Found) | The request failed because the admin to be deleted could not be found. |
| 409 (Conflict) | The request failed because the organisation the admin to be deleted belongs to has been disabled. |