Multi-Factor Authentication (MFA)

DocuTrust supports Time-Based One-Time Password (TOTP) MFA, compatible with any authenticator app that implements the TOTP standard (RFC 6238), including Google Authenticator, Authy, 1Password, and Microsoft Authenticator.

Setup Flow

Step 1: Initiate MFA Setup

Request a new TOTP secret and QR code for the authenticated user.

curl -X POST https://your-app.com/api/mfa/setup \
  -H "X-Auth-Token: YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

const response = await fetch("https://your-app.com/api/mfa/setup", {
  method: "POST",
  headers: {
    "X-Auth-Token": "YOUR_API_TOKEN",
    "Content-Type": "application/json"
  }
});
const data = await response.json();

Response 200 OK

{
  "secret": "JBSWY3DPEHPK3PXP",
  "qr_svg": "<svg xmlns='http://www.w3.org/2000/svg' width='200' height='200' viewBox='0 0 33 33'><path d='M1,1h1v1h-1z M2,1h1v1h-1z ...' fill='#000000'/></svg>",
  "provisioning_uri": "otpauth://totp/DocuTrust:user@example.com?secret=JBSWY3DPEHPK3PXP&issuer=DocuTrust"
}

Field	Type	Description
`secret`	string	The TOTP secret key. Users can enter this manually into their authenticator app if they cannot scan the QR code.
`qr_svg`	string	An SVG image of the QR code that encodes the provisioning URI. Render this in your UI for users to scan.
`provisioning_uri`	string	The `otpauth://` URI following the Google Authenticator Key URI format. Contains the secret, issuer, and account name.

Display the qr_svg to your user so they can scan it with their authenticator app. Alternatively, provide the secret for manual entry.

Step 2: Confirm MFA Setup

After the user scans the QR code and generates their first code, confirm the setup by submitting the 6-digit code.

curl -X POST https://your-app.com/api/mfa/confirm \
  -H "X-Auth-Token: YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "482916"
  }'

const response = await fetch("https://your-app.com/api/mfa/confirm", {
  method: "POST",
  headers: {
    "X-Auth-Token": "YOUR_API_TOKEN",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    code: "482916"
  })
});
const data = await response.json();

Request Body

Field	Type	Required	Description
`code`	string	Yes	The 6-digit TOTP code from the authenticator app.

Response 200 OK

{
  "enabled": true,
  "backup_codes": [
    "abc12345",
    "def67890",
    "ghi13579",
    "jkl24680",
    "mno35791",
    "pqr46802",
    "stu57913",
    "vwx68024"
  ]
}

Field	Type	Description
`enabled`	boolean	Whether MFA is now active on the account. Always `true` on successful confirmation.
`backup_codes`	array of strings	Eight single-use backup codes. Each code can be used once in place of a TOTP code if the user loses access to their authenticator app.

Store backup codes securely. They are only shown once at setup time and cannot be retrieved later. Each code can be used exactly once.

Step 3: Check MFA Status

Query the current MFA status for the authenticated user.

curl -X GET https://your-app.com/api/mfa/status \
  -H "X-Auth-Token: YOUR_API_TOKEN"

const response = await fetch("https://your-app.com/api/mfa/status", {
  headers: {
    "X-Auth-Token": "YOUR_API_TOKEN"
  }
});
const data = await response.json();

Response 200 OK

{
  "enabled": true,
  "backup_codes_remaining": 8
}

Field	Type	Description
`enabled`	boolean	Whether MFA is currently active for this user.
`backup_codes_remaining`	integer	The number of unused backup codes remaining. Starts at 8 and decrements each time a backup code is used.

Step 4: Disable MFA

Disable MFA by providing a valid TOTP code from the authenticator app.

curl -X DELETE https://your-app.com/api/mfa \
  -H "X-Auth-Token: YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "739201"
  }'

const response = await fetch("https://your-app.com/api/mfa", {
  method: "DELETE",
  headers: {
    "X-Auth-Token": "YOUR_API_TOKEN",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    code: "739201"
  })
});

Request Body

Field	Type	Required	Description
`code`	string	Yes	A valid 6-digit TOTP code from the authenticator app.

Response 200 OK

{
  "enabled": false
}

If account-level MFA enforcement is active (mfa_enforced setting), individual users cannot disable MFA. The request will return 403 Forbidden.

When MFA is enabled, the login flow becomes a two-step process:

Password authentication: The user submits their email and password to POST /login. If the credentials are valid and MFA is enabled, the response returns a 302 redirect to /mfa/verify instead of completing the login.
TOTP verification: The user is presented with a form to enter their 6-digit TOTP code (or a backup code). Upon successful verification, the session is created and the user is redirected to the dashboard.

POST /login
  email: "user@example.com"
  password: "SecureP@ssw0rd!"

  --> 302 Redirect to /mfa/verify (MFA required)

POST /mfa/verify
  code: "482916"

  --> 302 Redirect to /dashboard (login complete)

Account-Level MFA Enforcement

Administrators can enforce MFA for all users in the account by enabling the mfa_enforced setting in Settings > Security. When MFA enforcement is active:

Users who have not set up MFA are redirected to the MFA setup page on login and cannot access any other admin pages until MFA is configured.
Users cannot disable their own MFA (the disable endpoint returns 403 Forbidden).
New users must configure MFA as part of their first login.

Backup Codes

Each user receives 8 backup codes when MFA is first enabled. Backup codes are:

Single-use: Each code can only be used once.
Shown once: Codes are only displayed at MFA setup time. They cannot be retrieved later.
Equivalent to TOTP codes: A backup code can be entered anywhere a TOTP code is requested (login, disable MFA, etc.).
Tracked: The backup_codes_remaining field on the status endpoint shows how many unused codes remain.

If a user runs out of backup codes and loses access to their authenticator app, an administrator must disable MFA for that user from the admin panel.

Error Responses

Status	Error	Description
`400 Bad Request`	`"Invalid code"`	The provided TOTP or backup code is incorrect or expired.
`403 Forbidden`	`"MFA enforcement is active"`	Cannot disable MFA while account-level enforcement is enabled.
`409 Conflict`	`"MFA already enabled"`	Attempted to set up MFA when it is already active. Call `DELETE /api/mfa` first.
`422 Unprocessable Entity`	`"Setup not initiated"`	Attempted to confirm MFA without first calling `POST /api/mfa/setup`.

Getting Started

Core Guides

Embedding

Features

Security & Compliance

Legal

Multi-Factor Authentication

Multi-Factor Authentication (MFA)

Setup Flow

Step 1: Initiate MFA Setup

Step 2: Confirm MFA Setup

Step 3: Check MFA Status

Step 4: Disable MFA

Account-Level MFA Enforcement

Backup Codes

Error Responses

​Multi-Factor Authentication (MFA)

​Setup Flow

​Step 1: Initiate MFA Setup

​Step 2: Confirm MFA Setup

​Step 3: Check MFA Status

​Step 4: Disable MFA

​Login Flow with MFA

​Account-Level MFA Enforcement

​Backup Codes

​Error Responses

Multi-Factor Authentication (MFA)

Setup Flow

Step 1: Initiate MFA Setup

Step 2: Confirm MFA Setup

Step 3: Check MFA Status

Step 4: Disable MFA

Login Flow with MFA

Account-Level MFA Enforcement

Backup Codes

Error Responses