Login with MFA

Introduction

In this guide we will focus on setting up the MFA for your organization and how to login with MFA through API.

This guide is for organization admins, however, every user can enable MFA in the settings of his account.

Read more about MFA here - Security

Requirements

For enforcing the MFA in your organization, you need to have Circularo admin account.

However, to login with MFA, regular account is sufficient.

Step 0 - Enforce MFA in your organization

Go to Administration → Settings.

Toggle on the Enforce MFA option.

Step 1 - Login

Follow the authentication steps outlined in the Authentication Documentation.

Endpoint

POST /login

Request

POST /login

Content-Type: application/json

{
  "name": "mary.griffin@circularo.com",
  "password": "#32Password1!",
  "tenant": "default"
}

Response

{
  ...
  "isUnlocked": false,
  "token": "YkY1SH73DyRruW4KJDuqG7Es3A93l1GxulKzfKIk2ZNUtB8LwaauuVvR8hCElwkb",
  ...
}

Note: The token is locked initially. To access other endpoints, unlocking is required

If not unlocked following error will be encountered:

CODE

Access token is locked

Step 2 - Unlock the token

In previous step the MFA was invoked and dispatched. Assuming an email was designated as the MFA method, an email containing the code was sent.

Utilize the received code in the subsequent call.

Endpoint

POST /login/unlock

Request

POST /login/unlock

Content-Type: application/json

{
  "factors": [
    {
      "factor": "email",  //MFA provider other options are \"sms\" and \"totp\" for 3rd party app
      "password": "271008"
    }
  ]
}

Response

{
  "isUnlocked": true,
  "factors": [
    {
      "factor": "email",
      "unlocked": true
    }
  ]
}

Your token is now unlocked, permitting its use for invoking other endpoints.