API
API - is the program interface for interaction with the Multifactor system.
Operation principle
API uses REST architecture, all the requests and answers of API are transmitted in UTF-8 coding, in 'JSON' format with the obligatory indication of header
Content-Type: application/json
Any answer of the system includes at least two parameters: success
and message
.
{ 'success': false, 'message': 'Something wrong' }
Constant address of API — https://api.multifactor.ru
Authentication in API
For request authentication it is used HTTP Basic Auth:
- Login and password are separated by a colon (
login:pwd
) and are being encoded in base64bG9naW46cHdk
- The obtained value is transmitted in header
Authorization: Basic bG9naW46cHdk
Login is Api Key, password is Api Secret. Both these values are available in the administrator panel.
Ping
Function for verification of interaction with the system.
Address https://api.multifactor.ru/ping
, method GET, parameters are not required.
Example of system response:
{"model":"Pong","success":true,"message":null}
Access requests
Create request
Function to create a request for two-factor authentication.
Address https://api.multifactor.ru/access/requests
, method POST.
Request example:
{
identity: 'user@example.com', //user id
claims: //arbitrary set of parameters
{
'param1': 'value1',
'param2': 'value2',
},
callback: //user return address
{
action: 'https://example.com/mf/callback',
target: '_self'
}
}
Parameter | Function | Format |
---|---|---|
identity | Unique identifier of user in your system | Any |
claims | Arbitrary set of parameters to be incuded in JWT | json |
callback.action | Address on your web-site to return the user after successful authentication | Url |
callback.target | For placing the access page in iframe | _self, _parent, _top |
Response example:
{
'model':
{
'id':'620UNJe', //request id
'url':'https://access.multifactor.ru/620UNJe' //access page address
},
'success':true,
'message':null
}
Status test
Function for verification the status of request for two-factor authentication.
Address https://api.multifactor.ru/access/requests/[request ID]
, method GET.
Response example:
{
""model"": {
""identity"": ""test@test.local"", //user id
""status"": ""Granted"", //status
""url"": ""https://access.multifactor.ru/620UNJe"", //access page address
""accessToken"": ""ey...J9.ey...BTSJ9.al..RM"" //JWT (if status is Granted)
},
""success"": true,
""message"": null
}
This is an auxiliary function, in most cases, it is not required. Instead of this, please use verification of JWT token upon user return to your web-site.