Two factor authentication (2FA)
For increased security, Teamwire administrator accounts can be protected with a two factor authentication (2FA) mechanism, requiring the admin to supply a second authentication factor in addition to her password in order to be able to login.
Teamwire’s two factor authentication uses Time-based One-time Passwords (TOTP) as specified in RFC 6238, where for every login a separate device (such as an app on the Admin’s smartphone) uses a secret previously established with the Teamwire backend during 2FA setup and the current clock time to derive an additional PIN. The PIN will be valid for the single login and for a very short time period only.
Admin account 2FA recovery
Request 2FA token via text message (SMS)
POST /v<api_version>/admin/2fa/recover/
This endpoint can be used when an admin loses his 2FA credentials, e.g. because she loses access to this TOTP 2FA app. Calling it will cause a text message (SMS) to be sent to the admin’s mobile phone number containing a token which will allow her to login and modify her 2FA settings.
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 admin’s email address. |
mobile |
String | No | All admins | The admin’s mobile phone number. |
Result
The following return values indicate the outcome of the API call:
| HTTP status code | Description |
|---|---|
| 200 (OK) | The request was successful, a text message (SMS) has been sent to the admin. |
| 401 (Unauthorized) | The request failed because either a.) the supplied mobile phone number does not match the one stored in the admin’s profile or b.) two factor authentication has not been enabled for this admin. |
| 409 (Conflict) | The request failed because either the admin has not confirmed her email address and/or mobile number yet or she or her organisation has been disabled. |
| 429 (Too many requests) | The request failed because a text message (SMS) has just been sent and the caller needs to wait at least 60 seconds until this endpoint can be called again. |
Admin account 2FA settings
Complete 2FA setup
POST /v<api_version>/admin/2fa/
This endpoint needs to be called in order for the two factor authentication (2FA) setup for the admin’s account to be completed.
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 |
|---|---|---|---|---|
token |
String | No | All admins | A token as generated by a TOTP 2FA app after scanning the QR code generated by the xxx endpoint. |
Result
The following return values indicate the outcome of the API call:
| HTTP status code | Description |
|---|---|
| 200 (OK) | The request was successful. 2FA is now enabled for the admin’s account. |
| 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.) an invalid token was supplied. |
Initiate 2FA setup
GET /v<api_version>/admin/2fa/
Calling this endpoint will initiate two factor authentication (2FA) setup for the admin. A JPEG image of a QR code suitable for scanning with common TOTP 2FA apps such as e.g. Google Authenticator will be returned. The token generated by the 2FA app must then be submitted to the Complete 2FA setup endpoint in order for the 2FA setup to be completed.
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. |
Result
The following return values indicate the outcome of the API call:
| HTTP status code | Description |
|---|---|
| 200 (OK) | The request was successful. A JPEG image containing the QR code will be returned. A URL to this image will also be provided via the “Alt” header in the HTTP response. |
| 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 the calling admin’s organisation has been disabled. |
Disable 2FA
DELETE /v<api_version>/admin/2fa/
DELETE /v<api_version>/admin/2fa/<admin_email_hash>/
Calling this endpoint will disable two factor authentication for the calling admin or the specified admin.
Access restrictions
- Admins and Superadmins must have the allow_modify_admins permission in order to specify another admin’s admin_email_hash.
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 the admin for which 2FA should be disabled. If left off, 2FA will be disabled for the calling admin herself. |
Result
The following return values indicate the outcome of the API call:
| HTTP status code | Description |
|---|---|
| 200 (OK) | The request was successful. 2FA is now disabled for the admin’s account. |
| 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 a read-only admin or c.) the specified admin does not belong to the calling admin’s 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 2FA has already been disabled for the admin’s account. |