Multi-factor authentication

Multi-factor authentication can be enabled for all users. If your user requires multi-factor authentication then you will need to provide a Time-based One-Time Password (TOTP)-code in addition to your username and password.

Device registration

To initiate a Multi-factor device registration you first need to call the <xref:Monitor.API.Common.Commands.GetMultiFactorDeviceSecret> command. Below is an example response.

HTTP/1.1 200 OK
Content-Type: application/json
...
X-Monitor-SessionId: d497f3b1-a91a-4436-9ccd-45dc8c2eba79

{
  "$id": "1",
  "MfaToken": "Whuet4ts6CH9tutCwmCsApHN4tMWHiZMVrAN6p6UWdA=",
  "Secret": "N7BH4CQOCXFZZSY6NLQSAWXTWBYHIP2E",
  "QrCode": "iVBORw0KGgoAAAANSU...==",
  "ExpiryDate": "2023-02-21T13:32:03.5116414+01:00"
}

Then until ExpiryDate ends, you can use the Secret or QrCode to generate a TOTP-code that you should pass to the <xref:Monitor.API.Common.Commands.SetMultiFactorAuthenticationDevice> command along with the MfaToken to complete the device registration.

Failure

In case of the MfaToken token being expired, the response would look as follows.

HTTP/1.1 400 Bad Request
Content-Type: application/json

"Validation failed for command SetMultiFactorAuthenticationDevice: Invalid or expired MfaToken."

Authentication

Response

Below is an example response received after a login attempt that resulted in a multi-factor authentication being required.

HTTP/1.1 200 OK
Content-Type: application/json

{
  "$id": "1",
  "SessionId": null,
  "MfaToken": "5JWpAQiTXtBoZywjBOw47s4KSauoNtbEtRu0M-Ci3aghitBpiaXDHMr5fExY2Twv0"
}

The response body of the request will contain only null and false except for MfaToken which will contain a string that will be used as input to the /login/totp request. The MfaToken is valid for 1.5 minutes.

Request

Below is an example multi-factor authentication authentication request.

POST /{languageCode}/{companyNumber}/login/totp HTTP/1.1
Host: {host}:8001
Content-Type: application/json
Cache-Control: no-cache
Accept: application/json

{
  "MfaToken": "5JWpAQiTXtBoZywjBOw47s4KSauoNtbEtRu0M-Ci3aghitBpiaXDHMr5fExY2Twv0",
  "Code": 705005
}

Success

The same as a normal Authentication success.

Failure

In case of a multi-factor authentication failure, the responses would look as follows.

HTTP/1.1 410 Gone
Content-Type: application/json

"Login failed"

This typically occurs because the MfaToken is wrong or has expired.

HTTP/1.1 401 Unauthorized
Content-Type: application/json

"Login failed"

This typically occurs because the Code is wrong.