TOTP#

Tip

See RFC 6238 TOTP: Time-Based One-Time Password Algorithm.

Checking for TOTP availability#

Method

GET https://login.company.com/blitz/api/v3/users/{subjectId}/totps

Checking whether the user has a configured TOTP confirmation code generator.

Required permissions: blitz_api_usec or blitz_api_sys_usec.

Returns

If TOTP is configured, its settings will be received in response.

Example

GET /blitz/api/v3/users/d2580c98-e584-4aad-a591-97a8cf45cd2a/totps HTTP/1.1
Authorization: Bearer cNwIXatB0wk5ZHO0xG5kxuuLubesWcb_yPPqLOFWDuwzMDc0Nz
Cache-Control: no-cache

[
    {
        "id": "SW_TOTP_1_d2580c98-e584-4aad-a591-97a8cf45cd2a",
        "len": 6,
        "name": "Google Authenticator"
    }
]

TOTP linking#

Linking to the user account of the TOTP generator is carried out in two stages.

Stage No.1

Method

GET https://login.company.com/blitz/api/v3/users/{subjectId}/totps/attach/qr

Request for a QR code and a linking string in Blitz Identity Provider.

Required permissions: blitz_api_usec_chg``or ``blitz_api_sys_usec_chg.

Headers

In user mode, headers with the user’s IP address and User-Agent must be passed.

Returns

Attributes:

  • base64QRCode is the QR code of the generator linking that needs to be displayed to the user;

  • base32Secret is a secret generator linking string that needs to be displayed to the user if it is inconvenient for him to photograph the QR code and he prefers to enter the linking code into the generator manually.

Example

GET /blitz/api/v3/users/d25..2a/totps/attach/qr HTTP/1.1
Authorization: Bearer cN..z
Cache-Control: no-cache

{
    "base64QRCode": "iVB…g==",
    "base32Secret": "W247OHVTPPTIAOXMGKK6Z7BZ3DEYWO74"
}

Stage No.2

Method

POST https://login.company.com/blitz/api/v3/users/{subjectId}/totps/attach/qr

Confirmation of linking registration.

Required permissions: blitz_api_usec_chg``or ``blitz_api_sys_usec_chg.

Request body

  • base32Secret is the secret initialization string of the TOTP generator;

  • otpCode is the confirmation code generated by the generator using the TOTP algorithm from the secret string and the current time slot;

  • name is the display name of the TOTP generator (optional).

Returns

  • If successful - HTTP 204 No Content.

  • In case of an error, the service - HTTP 400 Bad Request.

Example

POST /blitz/api/v3/users/d2580c98..cd2a/totps/SW_TOTP_1_d2580c98..cd2a HTTP/1.1
Content-Type: application/json
X-Forwarded-For: 200.200.100.100
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_5)

{
    "base32Secret": "W247OHVTPPTIAOXMGKK6Z7BZ3DEYWO74",
    "name": "Google Authenticator",
    "otpCode": "123456"
}

{
    "base64QRCode": "iVB…g==",
    "base32Secret": "W247OHVTPPTIAOXMGKK6Z7BZ3DEYWO74"
}
The wrong code was passed#
{
    "type": "process_error",
    "error": "wrong_otp_code"
}

Deleting the linking#

Method

DELETE https://login.company.com/blitz/api/v3/users/{subjectId}/totps/{id}

Deleting the linking of the TOTP generator to the user account.

Required permissions: blitz_api_usec_chg``or ``blitz_api_sys_usec_chg.

URL parameters

The id is specified as received linking ID.

Headers

In user mode, headers with the user’s IP address and User-Agent must be passed.

Returns

If successful, the service will return HTTP 204 No Content.

Example

Request#
DELETE /blitz/api/v3/users/d..2a/totps/SW_TOTP_1_d..2a HTTP/1.1
Authorization: Bearer cN..z
X-Forwarded-For: 200.200.100.100
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_5)...