API Endpoints

MFA method activation

Request a new method activation and get an authentication code by specified channel.

Request

POST /:method_name/activate/

Parameters

:method_name - required

Allowed method names: email, app, yubi, sms_api, sms_twilio

Successful response

 
{
    "details": "Email message with MFA code has been sent."
}

HTTP status: 200 OK

Error response

 
{
    "error": "Requested MFA method does not exist."
}

HTTP status: 400 BAD REQUEST

MFA method activation confirmation

Accepts the authentication code, activates the method and returns backup codes if successful.

Request

POST /:method_name/activate/confirm/

Parameters

:method_name - required

Allowed method names: email, app, yubi, sms_api, sms_twilio

Payload

 
{
    "code": "123456"
}

code - authentication code received by specified method

Successful response

 
{
    "backup_codes": [
        "111111",
        "222222",
        "333333",
        "444444",
        "555555",
        "666666",
    ]
}

HTTP status: 200 OK

Error response

 
{
    "error": "MFA method already active."
}

HTTP status: 400 BAD REQUEST

MFA method deactivation

Deactivates the specified method. Depeding on :doc: settings sends out an authentication code and requires confirmation.

Request

POST /:method_name/deactivate/

Parameters

:method_name - required

Allowed method names: email, app, yubi, sms_api, sms_twilio

Payload

 
{
    "code": "123456"
}

code - authentication code received by specified method

Successful response

empty

HTTP status: 204 NO CONTENT

Error response

 
{
    "error": "Requested MFA method does not exist."
}

HTTP status: 400 BAD REQUEST

Send the code

Triggers sending out a code. If no method specified in the payload user’s primary MFA method will be used.

Request

POST /code/request/

Payload

 
{
    "method": "email"
}

method (optional) - one of: email, app, yubi, sms_api, sms_twilio

Successful response

empty

HTTP status: 200 OK

Error response

 
{
    "details": "Email message with MFA code has been sent."
}

HTTP status: 400 BAD REQUEST

Login - first step (JWT example)

If MFA is enabled for a given user returns ephemeral_token required in next step as well as current auth method.
Otherwise returns access and refresh tokens.

Request

POST /login/

Payload

 
{
    "username": "Merixstudio",
    "password": "SecretPassword123#"
}

Successful response (MFA enabled)

 
{
    "ephemeral_token": "1-qrx0ph-e76b858094f0321525b42ad7141b5720816b6a4c",
    "method": "email"
}

HTTP status: 200 OK

Successful response (MFA disabled)

 
{
    "access": "eyJhbGciOiJIUzI1NiIsInR5cCI...AhJA",
    "refresh": "eyJhbGciOiJIUzI1NiIsInR5cCI...T_t8"
}

HTTP status: 200 OK

Error response

 
{
    "details": "Unable to login with provided credentials."
}

HTTP status: 401 UNAUTHENTICATED

Login - second step (JWT example)

Requires ephemeral_token generated in previous step and OTP code.
Returns access and refresh tokens after successful authentication.

Request

POST /login/code/

Payload

 
{
    "ephemeral_token": "1-qrx0ph-e76b858094f0321525b42ad7141b5720816b6a4c",
    "code": "925738"
}

Successful response

 
{
    "access": "eyJhbGciOiJIUzI1NiIsInR5cCI...AhJA",
    "refresh": "eyJhbGciOiJIUzI1NiIsInR5cCI...T_t8"
}

HTTP status: 200 OK

Error response

 
{
    "details": "Unable to login with provided credentials."
}

HTTP status: 401 UNAUTHENTICATED

Generate new backup codes

If you’ve set the CONFIRM_BACKUP_CODES_REGENERATION_WITH_CODE option to True in the :doc: settings then passing the code in request payload is required.

Request

POST /:method_name/codes/regenerate/

Parameters

:method_name - required

Allowed method names: email, app, yubi, sms_api, sms_twilio

Payload

 
{
    "code": "123456"
}

code - authentication code received by specified method

Successful response

 
{
    "backup_codes": [
        "111111",
        "222222",
        "333333",
        "444444",
        "555555",
        "666666",
    ]
}

HTTP status: 200 OK

Error response

 
{
    "error": "Requested MFA method does not exist."
}

HTTP status: 400 BAD REQUEST

Get configuration

Returns MFA configuration

Request

GET /mfa/config/

Successful response

 
{
    "methods": [
        "sms_twilio",
        "sms_api",
        "email",
        "app",
        "yubi"
    ],
    "confirm_disable_with_code": true,
    "confirm_regeneration_with_code": true,
    "allow_backup_codes_regeneration": true
}

HTTP status: 200 OK

Get user’s active MFA methods

Display methods activated by user

Request

GET /mfa/user-active-methods/ Authorization: Bearer ACCESS_TOKEN

ACCESS_TOKEN is used for JWT authentication. For other types use the authorization header accordingly.

Successful response

 
[
    {
        "name": "email",
        "is_primary": true
    },
    {
        "name": "yubi",
        "is_primary": false
    }
]

HTTP status: 200 OK

Change user’s primary MFA method

Change user’s primary authentication method.
Display methods activated by user

Request

POST /mfa/change-primary-method/ Authorization: Bearer ACCESS_TOKEN

ACCESS_TOKEN is used for JWT authentication. For other types use the authorization header accordingly.

Payload

 
{
    "method": "yubi",
    "code": "123456"
}

method - one of: email, app, yubi, sms_api, sms_twilio code - authentication code received by specified method

Successful response

empty

HTTP status: 204 NO CONTENT

Error response

 
{
    "error": "MFA Method selected as new primary method is not active"
}

HTTP status: 400 BAD REQUEST