Glue API: Authenticate through MFA

Last updated:
Edit on GitHub

This document describes how to authenticate through Multi-Factor Authentication (MFA) to send requests to protected resources.

The email authentication method is used as an example. The endpoint supports all authentication methods implemented in your project.

Installation

Prerequisites

Activate MFA for your user

Request an MFA code

To request an MFA code, sent the request:

POST /multi-factor-auth-trigger

Request

HEADER KEY TYPE REQUIRED DESCRIPTION
Authorization string ✓ String containing digits, letters, and symbols that authorize the company user. To get the value, authenticate as a company user, authenticate as a customer, or authenticate as a Back Office user. 
POST /multi-factor-auth-trigger
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "data": {
    "type": "multi-factor-auth-trigger",
    "attributes": {
      "type": "email"
    }
  }
}

Response

204 No Content — means that the code has been sent through the requested method.

The default grace period allows the authenticated account to send requests to protected resources for 30 minutes.

Send requests to protected resources with MFA

Include the MFA code you’ve received in the X-MFA-Code header when calling protected endpoints.

Example request

HEADER KEY TYPE REQUIRED DESCRIPTION
Authorization string ✓ String containing digits, letters, and symbols that authorize the user. To get the value, authenticate as a company user, authenticate as a customer, or authenticate as a Back Office user.
X-MFA-Code string ✓ String containing digits, letters, and symbols that authorize the user through MFA. To get the value, request an MFA code.

This example request shows how to change account password with MFA:

PATCH /customer-password/DE--42
Authorization: Bearer <access_token>
X-MFA-Code: <your_mfa_code>
Content-Type: application/json

{
  "data": {
    "type": "customer-password",
    "attributes": {
      "password": "oldPass123",
      "newPassword": "NewPass456!",
      "confirmPassword": "NewPass456!"
    }
  }
}

Example error response

A successful response doesn’t contain any MFA related information. However, an unsuccessful response might contain such information:

{
  "errors": [
    {
      "status": 403,
      "code": "5900",
      "detail": "X-MFA-Code header is missing."
    }
  ]
}

Possible errors

Code Constant Meaning
5900 ERROR_CODE_MULTI_FACTOR_AUTH_CODE_MISSING X-MFA-Code header is missing.
5901 ERROR_CODE_MULTI_FACTOR_AUTH_CODE_INVALID X-MFA-Code is invalid.
5902 ERROR_CODE_MULTI_FACTOR_AUTH_TYPE_MISSING MFA type is missing.
5903 ERROR_CODE_MULTI_FACTOR_AUTH_DEACTIVATION_FAILED Failed to deactivate MFA.
5904 ERROR_CODE_MULTI_FACTOR_AUTH_VERIFY_FAILED MFA type already activated.
5905 RESPONSE_CODE_NO_CUSTOMER_IDENTIFIER No customer identifier provided.
5906 ERROR_CODE_MULTI_FACTOR_AUTH_TYPE_NOT_FOUND MFA type is not found.
5907 RESPONSE_CUSTOMER_NOT_FOUND Customer not found.
5908 RESPONSE_USER_NOT_FOUND User not found.
5909 RESPONSE_CODE_NO_USER_IDENTIFIER No user identifier provided.