Skip to main content

User Management API

The API for managing users (subjects of access) in MULTIFACTOR.

API access

Before using this API, you must enable the extended API in personal account, in the "API Settings" section and use the API Key and API Secret provided in the section.

User management

Number of users and licenses

Address https://api.multifactor.kz/users/count | method GET.

Function for requesting the current disposal of licenses in the MULTIFACTOR system.

Example request:

GET https://api.multifactor.kz/users/count

Sample answer:

{
"model": {
total: 5000, //number of users
limit: 6000 //number of licenses
},
"success": true,
"message": null
}

List of users

Address https://api.multifactor.kz/users | method GET.

Example request:

GET https://api.multifactor.kz/users

To search for a specific user by login, use the Identity query parameter:

GET https://api.multifactor.kz/users?identity=user@example.com

To include user phone numbers (if available) in the server response, use the withPhones query parameter with the value true:

GET https://api.multifactor.kz/users?withPhones=true

Sample answer:

{
"model": [ //list of users
{
"id": "5e3c1058c3a23e55b0579ded", //user id in MULTIFACTOR
"identity": "user@example.com", //user login on your system
"name": null,
"email": null,
"isEnrolled": true, //the second factor is configured
"createdAt": "2020-02-06T13:10:48.139Z",
"lastLogin": "2021-06-01T15:42:46.786Z",
"isLocked": false,
"groups": [ //groups the user is a member of
"AllUsers"
"Super Admin Web"
],
"authenticators": [ //configured authentication methods
"Telegram"
],
}
],
"success": true,
"message": null
}

User registration

Address https://api.multifactor.kz/users | POST method.

Users are registered automatically the first time they visit the access page, but there is also an option to register via the API.

Example request:

{
"Identity": "user@example.com", //user login on your system
"Email": "user@example.com", //e-mail, optional
"Phone": null, //phone, optional
"Name": "User Name", //name, optional
"EnrollmentLink": //send a link for setup, optional
{
"To": "email", //to the email specified above
"Ttl": 90 //with a validity period of 90 minutes
},
"Groups": {
"Add": ["Group1 name", "Group2 name"] //add user to groups (optional)
}
}

Example response: User registered

{
"model": {
"id": "5e3c1058c3a23e55b0579ded",
"identity": "user@example.com",
"name": "User Name",
"email": "user@example.com",
"isEnrolled": false,
"createdAt": "2020-03-05T11:55:43.8001916Z",
"lastLogin": null,
"isLocked": false
},
"success": true,
"message": null
}

Modifying User Data

Address https://api.multifactor.kz/users/{id} | PUT method.

  • The id parameter is the user identifier.

Used to change data, block and unblock the user.

Example request:

{ 
"Identity": "user@example.com", //if you need to change the login
"Name": "User Name", //if you need to change the name
"Email": "user@example.com", //if you need to change the address
"IsLocked": true, //if you need to block
"Groups": {
"Add": ["Group1 name", "Group2 name"], //if you need to add a user to groups
"Remove": ["Group3 name", "Group4 name"], //if you need to remove the user from groups (optional)
}
}

Example response:

{
"model": {
"id": "5e3c1058c3a23e55b0579ded",
"identity": "user@example.com",
"name": "User Name",
"email": "user@example.com",
"isEnrolled": false,
"createdAt": "2020-03-05T11:55:43.8001916Z",
"lastLogin": null,
"isLocked": true
},
"success": true,
"message": null
}

Deleting a user

Address https://api.multifactor.kz/users/{id} | method DELETE.

  • The id parameter is the user identifier.

Example request:

DELETE https://api.multifactor.kz/users/1234567890

Sample answer:

{
"success": true,
"message": null
}

Address https://api.multifactor.kz/users/{id}/enroll | POST method.

  • The id parameter is the user identifier.

This function generates and sends a setup link to the user's email. If the Email parameter is not specified, the link will be generated without sending the email and will be returned in the server response.

Example request:

{
"Email": "user@example.com", //[optional] address where to send the letter,
"Ttl": 90 //link expiration date (90 minutes)
}

Example response:

{
"success": true,
"message": null
}

Authenticator management

Connected authentication methods

Address https://api.multifactor.kz/users/{id}/authenticators | method GET.

Options:

  • id — user identifier.

Example request:

GET https://api.multifactor.kz/users/1234567890/authenticators

Example response:

{
"model": {
"Telegram": [
{
"id": "627d3d4f410ae00ede026358",
"name": "User Name"
}
],
"TotpToken": [
{
"id": "627e7ffec027bb87054ea6e3",
"name": "Yandex.Key"
},
{
"id": "627e8041c027bb87054ea6e4",
"name": "Microsoft"
}
],
"HotpToken": [
{
"id": "62829fb2e0270cb2ea95208c",
"name": "YubiKey 1234567"
}
]
},
"success": true,
"message": null
}

Renaming an authenticator

Address https://api.multifactor.kz/users/{id}/authenticators/{type}/{authenticatorid} | PUT method.

Options:

  • id — user identifier;
  • type — authentication method;
  • authenticatorid — authenticator identifier.

Example request:

PUT https://api.multifactor.kz/users/1234567890/authenticators/hotptoken/23456789

Parameters in the request body:

{
"Name": "Blue Rutoken"
}

Example response:

{
"success": true,
"message": null
}

Removing an authenticator

Address https://api.multifactor.kz/users/{id}/authenticators/{type}/{authenticatorid} | method DELETE.

Options:

  • id — user identifier;
  • type — authentication method;
  • authenticatorid — authenticator identifier.

Example request:

DELETE https://api.multifactor.kz/users/1234567890/authenticators/telegram/23456789

Example response:

{
"success": true,
"message": null
}

This function can also be called without specifying authenticatorid. In this case, all configured authenticators of the specified type will be deleted.

Example request:

DELETE https://api.multifactor.kz/users/1234567890/authenticators/telegram

Example response:

{
"success": true,
"message": null
}

OTP token registration

Address https://api.multifactor.kz/users/{id}/authenticators/{type} | POST method.

Options:

  • id — user identifier;
  • type — token type:
    • totptoken — TOTP token;
    • hotptoken — HOTP token.

Supported hashing algorithms:

  • TOTP token: SHA-1 (6 digits);
  • HOTP token: SHA-1, SHA-256, SHA-512 (6 digits).

Example request:

POST https://api.multifactor.kz/users/1234567890/authenticators/hotptoken

Request body parameters:

{ //example of Rutoken OTP registration
"Name": "Rutoken HOTP", //arbitrary name
"Key": "673c7514b68e8f09707cc6a4321aa76673a688d4" //key in hex encoding
}

Another example:

{ //example of YubiKey OTP registration
"Name": "YubiKey 1234567", //arbitrary name
"Key": "9b617117c2a4862f47caf4fb2e4032ac", //key in hex encoding
"PrivateId": "2fc5120aca42" //uid in hex encoding
}

Example response:

{
"success": true,
"message": null
}

Moving OTP token

Address https://api.multifactor.kz/users/{id}/authenticators/{type}/{tokenid} | PUT method.

Parameters:

  • id — user identifier;
  • type — token type:
    • totptoken — TOTP token;
    • hotptoken — HOTP token;
  • tokenid — token identifier.

Function for moving OTP token between users. When moved, the token is detached from the old user and attached as an authentication method to the target user.

Example request:

PUT https://api.multifactor.kz/users/1234567890/authenticators/hotptoken/23456789

Request body parameters:

{
"user": "1234567890", //target user ID
"name": "White Rutoken" //[optional] new name of the authenticator
}

Example response:

{
"success": true,
"message": null
}

Copying OTP token

Address https://api.multifactor.kz/users/{id}/authenticators/{type}/{tokenId} | PATCH method.

Parameters:

  • id — user identifier;
  • type — token type:
    • totptoken — TOTP token;
    • hotptoken — HOTP token;
  • tokenid — token identifier.

Function to copy the OTP token of the source user to one or more target users. When copying, the token is not detached from the original user.

Example request:

PATCH https://api.multifactor.kz/users/1234567890/authenticators/hotptoken/23456789

Request body parameters:

{
"users": [
"1234567890", //target user ID 1
"1234567890" //target user ID 2
]
}