Obtaining a token. VMS Client API
Authorizing a user based on their login and password.
If the limit of concurrent sessions that a user can create is exceeded, a 429 error will be returned, and it will be necessary to remove the extra sessions.
POST /api/v1/token Headers
Accept
application/json
Body
json
JSON
{
"login": "mylogin@mail.com",
"password": "mypassword",
"session_id": "null|session_id",
"captcha": "9U6yh",
"key": "$2y$10$3gXEas4WVUryBA8GgF37vulJz1UrAo2VaYbWccaxeNYoZ.3UJqHYu"
} loginrequired
string
User login
passwordrequired
string
User password
session_idrequired
string
Token identifier received in case of a 419 status, to allow deleting that session
captcharequired
string
Captcha (see Getting captcha ). It is optional if captcha is disabled in the system settings
keyrequired
string
Key (см. Getting captcha ). It is optional if captcha is disabled in the system settings
Response
200
Returns a JSON object with the API access token and the current user object
JSON
{
"user": {
"id": 13,
"login": "user",
"name": "user",
"parent_id": null,
"permissions": [
{
"id": 223,
"name": "any-permission"
},
{
"id": 221,
"name": "any-permission"
},
{
"id": 222,
"name": "any-permission"
},
{
"id": 220,
"name": "any-permission"
}
],
"created_at": "",
"updated_at": "2022-04-21 16:37:46",
"access_token_id": "c862e3c5a5a87d8b2756e4ad44a43f0a71cbf9cf3063cae019802d0b032ee17f32f69364e7aadb23",
"can_update_password": true,
"analytic_license": [
{
"type": "analytic_l1",
"type_pretty": "LIC-XXXX-YY-L1",
"all": 100,
"free": 98,
"used": 2
},
{
"type": "analytic_l2",
"type_pretty": "LIC-XXXX-YY-L2",
"all": 100,
"free": 100,
"used": 0
},
{
"type": "analytic_l3",
"type_pretty": "LIC-XXXX-YY-L3",
"all": 100,
"free": 99,
"used": 1
}
]
},
"access_token": "Bearer token"
} 422
Returns a JSON object with an error, see Validation
JSON
{
"message": "There won't be any informative message here",
"errors": {
"any_key": [
"Here the error cause will be described"
]
}
} 419
The number of sessions has been exceeded. Returns information about active sessions
JSON
{
"sessions": [
{
"id": "session_id",
"is_current": false,
"user_agent": "Xiaomi / M2102J20SG / 11 / 1.1.0 / Android",
"client": "android",
"online": true,
"ip": "127.0.0.1"
}
],
"sessions_limit": 5,
"sessions_count": 5,
"captcha_will_required_in": 120
} integer
captcha_will_required_in
If the captcha is valid but the session limit is exceeded, the captcha will be considered valid for 120 seconds (as in the example). If a longer period of time has passed, it is necessary to obtain a new captcha. This field will be present only if the captcha is enabled
429
The maximum number of token retrieval attempts has been exceeded
JSON
There are two throttling mechanisms in place simultaneously:
1. There are 10 attempts to send a request from the same IP address within 10 minutes.
2. There are 10 attempts to send a token retrieval request for a specific login.
Example
JSON
curl -k --location --request POST 'https://vms.local/api/v1/token' \
--header 'Accept:application/json' \
--header 'Content-Type: application/json \
--data-raw '{
"login": "mylogin@mail.com",
"password": "mypassword",
"session_id": "null|session_id",
"captcha": "9U6yh",
"key": "$2y$10$3gXEas4WVUryBA8GgF37vulJz1UrAo2VaYbWccaxeNYoZ.3UJqHYu"
}'
