Registration
Admins will need to register once in order to be able to log in to the Enterprise API. Registration also encompasses email, mobile number and account confirmations.
Admin account registration
Register as a new admin
POST /v<api_version>/admin/register/
Since there are no default admin accounts in a Teamwire installation, new admins need to register using this endpoint in order to be able to access other parts of the Enterprise API.
There are a number of aspects that need to be taken into consideration when registering:
-
Every new admin will need to confirm her email address by submitting the secret that has been sent to this very email address to the email confirmation endpoint.
-
They will also need to confirm their mobile phone number by supplying the PIN sent to them via text message (SMS) to the mobile phone number confirmation endpoint.
-
An admin always belongs to exactly one organisation. During registration the organisation is determined by looking at the domain part of the supplied email address: if there is none covering the supplied email domain it will be created automatically.
-
In freshly set up on-premise installations without existing admin accounts, the first admin to register will immediately be able to use her account and also automatically become Superadmin, thus having access to manage other organisations. Superadmins can extend their privileges to other confirmed admins via the Updating endpoint.
-
With on-premise installations with at least one existing admin account and with the Teamwire cloud service, new admin registrations will require confirmation: by one of the existing admins of the organisation (if these exist) or one of the Superadmins.
Because of the behavior described above it is vital that all of a company’s email domains have been added to the organisation before successive admin registrations occur, e.g. immediately after the first admin for an organisation has been confirmed. Otherwise these admins could end up in logically separate organisations that would have to be merged together later on.
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 new admin’s first name. |
last_name |
String | No | All admins | The new admin’s last name. |
password |
String | No | All admins | The new admin’s password. |
email |
String | No | All admins | The new admin’s email address. |
mobile |
String | No | All admins | The new admin’s mobile phone number. |
phone |
String | No | All admins | The new admin’s landline phone number. |
company |
String | No | All admins | The new admin’s company. |
division |
String | No | All admins | The new admin’s division or department. |
role |
String | No | All admins | The new admin’s role within his division/department. |
city |
String | No | All admins | The new admin’s city. |
postcode |
String | No | All admins | The new admin’s post code. |
country |
String | No | All admins | The new admin’s country. |
address |
String | No | All admins | The new admin’s postal address. |
email_confirmation_link |
String | No | All admins | The base URL to embed in the confirmation email sent to the admin’s email address. The Teamwire backend will automatically append the particular secret, so this value should end in something like ?secret=. This way as soon as the user clicks on the link in the received email, the URL (which is assumed to be part of your Enterprise API client application) will be called and be responsible for calling the email confirmation endpoint with the received secret. |
Result
The following return values indicate the outcome of the API call:
| HTTP status code | Description |
|---|---|
| 200 (OK) | The request was successful, the new admin registration has been received. |
| 400 (Bad request) | The request failed because an admin with this email address already exists. |
| 400 (Bad request) | The request failed admin password do not match organisation password policy |
| 409 (Conflict) | The request failed because the organisation the new admin would belong to has been disabled. |
Admin mobile phone number confirmation
Confirm an admin’s mobile phone number
POST /v<api_version>/admin/register/confirm_mobile/
For Enterprise API consumers that implement the registration process it is recommended to ask the user for the received PIN after having sent a request to the registration endpoint. The entered PIN should then be submitted to this endpoint before proceeding to email confirmation.
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 |
|---|---|---|---|---|
email |
String | No | All admins | The email address of the admin to confirm the mobile phone number for. |
pin |
String | No | All admins | The PIN as received by text message (SMS). |
Result
The following return values indicate the outcome of the API call:
| HTTP status code | Description |
|---|---|
| 200 (OK) | The request was successful, the mobile phone number has been confirmed. |
| 403 (Forbidden) | The request failed because either a.) no admin registration that needs confirmation could be found using this email address or b.) the supplied PIN was wrong. |
Admin email address confirmation
Confirm an admin’s email address
POST /v<api_version>/admin/register/confirm_email/
Note that this endpoint has two peculiarities that are likely to be changed in the near future:
- Currently the email sent to the email address specified by the new admin during registration contains a link that points directly to this endpoint. The endpoint therefore deviates from other endpoints by returning a HTML response suitable for display in the admin’s web browser instead of JSON.
- The HTML is also currently generated using a template located in the backend’s filesystem which therefore can not be modified.
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 |
|---|---|---|---|---|
secret |
String | No | All admins | The secret as received via Email. |
admin_confirmation_link |
String | No | All admins | The base URL to embed in the email sent to other admins asking to confirm the new admin. The Teamwire backend will automatically append an auth code, so this value should end in something like ?auth=. This way as soon as another admin clicks on the link in the received email, the URL (which is assumed to be part of your Enterprise API client application) will be called and be responsible for calling the admin account confirmation endpoint with the received auth code. |
Result
The following return values indicate the outcome of the API call:
| HTTP status code | Description |
|---|---|
| 200 (OK) | The request was successful, the email address has been confirmed. |
| 403 (Forbidden) | The request failed because either a.) the email address has already been confirmed or the b.) an invalid secret was provided. |