Backend API: Manage Multi-Factor Authentication

This document describes how Back Office users and merchant users manage their Multi-Factor Authentication (MFA) methods using the Backend API, and how they send requests to MFA-protected Backend API resources.

The email authentication method is used as an example. The endpoints support all authentication methods registered in your project.

Installation

These endpoints are implemented using API Platform. To install and enable it, see Enable API Platform.

For the module that provides the endpoints and its installation instructions, see Install the Multi-Factor Authentication feature.

Conventions

Request headers and the error envelope are the same for every Backend API resource—see Backend API conventions. This page lists only what is specific to MFA.

All endpoints require a Back Office user or merchant user access token. To get one, see Authenticate as a Back Office user. A token that belongs to neither user type gets 403.

Every endpoint works on the MFA settings of the user the token belongs to. Back Office users and merchant users share the same MFA settings, so a method activated in the Back Office, in the Merchant Portal, or through this API applies everywhere.

Retrieve MFA methods

To retrieve the MFA methods registered in the project and their status for the authenticated user, send the request:

GET /multi-factor-auth-types

Request

Response

{
    "data": [
        {
            "type": "multi-factor-auth-types",
            "id": "email",
            "attributes": {
                "type": "email",
                "status": "deactivated"
            },
            "links": {
                "self": "https://glue-backend.mysprykershop.com/multi-factor-auth-types/email"
            }
        }
    ]
}

Activate an MFA method

Activation takes two steps: start the activation to receive a code through the method, then verify the code. Until the code is verified, the method stays in the activation is pending status.

To start the activation, send the request:

POST /multi-factor-auth-type-activate

Request

If the user already has an activated method, the request must carry a valid code of that method in the X-MFA-Code header. To get one, request an MFA code.

POST /multi-factor-auth-type-activate
Authorization: Bearer <access_token>
Content-Type: application/vnd.api+json

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

Response

204 No Content means that the method is in the activation is pending status and a verification code was sent through it.

Verify an MFA method

To finish the activation, send the code you received:

POST /multi-factor-auth-type-verify

Request

POST /multi-factor-auth-type-verify
Authorization: Bearer <access_token>
X-MFA-Code: 482913
Content-Type: application/vnd.api+json

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

Response

204 No Content means that the method is activated. From now on, requests to protected resources require a valid X-MFA-Code header.

Request an MFA code

To receive a code through an activated method, send the request:

POST /multi-factor-auth-trigger

Request

POST /multi-factor-auth-trigger
Authorization: Bearer <access_token>
Content-Type: application/vnd.api+json

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

Response

204 No Content means that the code was sent through the requested method.

A code is valid for the configured validity time, 30 minutes by default, and for the configured number of attempts, three by default. To change them, see Configure MFA code validity time for users and Configure brute-force protection limit for users.

Deactivate an MFA method

To deactivate an activated method, send a valid code of that method with the request:

POST /multi-factor-auth-type-deactivate

Request

POST /multi-factor-auth-type-deactivate
Authorization: Bearer <access_token>
X-MFA-Code: 482913
Content-Type: application/vnd.api+json

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

Response

204 No Content means that the method is deactivated.

Send requests to protected resources

When the user has an activated MFA method, POST, PATCH, and DELETE requests to the resources listed in MultiFactorAuthConfig::getMultiFactorAuthProtectedBackendResources() must carry a valid code in the X-MFA-Code header. GET requests are never checked. To configure the list, see Configure protected resources for Backend API.

To pass such a request, request an MFA code and add it to the request:

POST /warehouse-user-assignments
Authorization: Bearer <access_token>
X-MFA-Code: 482913
Content-Type: application/vnd.api+json

A successful response contains no MFA-specific information. A request without the header gets 403 with the error code 5900; a request with a wrong, expired, or already used code gets 403 with the error code 5901.

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

Possible errors

To view generic errors, see API errors and troubleshooting.