User Management API
The API for managing users (subjects of access) in MULTIFACTOR.
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
}
Link to configure the second factor
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
]
}