Authentication and password management API reference for on-premises management consoles
Article 10/18/2022
2 contributors
Feedback
In this article
This article lists the authentication and password management REST APIs supported for Microsoft Defender for IoT on-premises management consoles.
set_password (Change password)
Use this API to let users change their own passwords. All Defender for IoT user roles can work with the API.
You don't need a Defender for IoT access token to use this API.
URI : /external/authentication/set_password
POST
Type : JSON
Example :
request:
{
"username": "test",
"password": "Test12345\!",
"new_password": "Test54321\!"
}
Request parameters
Name Type Required / Optional
username String
Required
password String
Required
new_password String
Required
Type : JSON
Message
Description
Success – msg Password has been replaced
Failure – error User authentication failure
Failure – error Password does not match security policy
Response example
response:
{
"error": {
"userDisplayErrorMessage": "User authentication failure"
}
}
Type : POST
API :
curl -k -d '{"username": "<USER_NAME>","password": "<CURRENT_PASSWORD>","new_password": "<NEW_PASSWORD>"}' -H 'Content-Type: application/json' https://<IP_ADDRESS>/external/authentication/set_password
Example :
curl -k -d '{"username": "myUser","password": "1234@abcd","new_password": "abcd@1234"}' -H 'Content-Type: application/json' https://127.0.0.1/external/authentication/set_password
set_password_by_admin (User password update by system admin)
Use this API to let system administrators change passwords for specified users. Defender for IoT admin user roles can work with the API.
You don't need a Defender for IoT access token to use this API.
URI : /external/authentication/set_password_by_admin
POST
Type : JSON
Request example
request:
{
"admin_username": "admin",
"admin_password: "Test0987"
"username": "test",
"new_password": "Test54321\!"
}
Request parameters
Name Type Required / Optional
admin_username String
Required
admin_password String
Required
username String
Required
new_password String
Required
Type : JSON
Message string with the operation status details:
Message
Description
Success – msg Password has been replaced
Failure – error User authentication failure
Failure – error User does not exist
Failure – error Password doesn't match security policy
Failure – error User does not have the permissions to change password
Response example
response:
{
"error": {
"userDisplayErrorMessage": "The user 'test_user' doesn't exist",
"internalSystemErrorMessage": "The user 'yoavfe' doesn't exist"
}
}
Device fields
Name Type Required / Optional
admin_username String
Required
admin_password String
Required
username String
Required
new_password String
Required
Type : POST
API :
curl -k -d '{"admin_username":"<ADMIN_USERNAME>","admin_password":"<ADMIN_PASSWORD>","username": "<USER_NAME>","new_password": "<NEW_PASSWORD>"}' -H 'Content-Type: application/json' https://<IP_ADDRESS>/external/authentication/set_password_by_admin
Example :
curl -k -d '{"admin_user":"adminUser","admin_password": "1234@abcd","username": "myUser","new_password": "abcd@1234"}' -H 'Content-Type: application/json' https://127.0.0.1/external/authentication/set_password_by_admin
validation (Authenticate user credentials)
Use this API to validate user credentials.
You don't need a Defender for IoT access token to use this API.
URI : /external/authentication/validation
POST
Type : JSON
Query parameters
Name Type Required/Optional
username String
Required
password String
Required
Request example
request:
{
"username": "test",
"password": "Test12345\!"
}
Type : JSON
Message string with the operation status details:
Message
Description
Success - msg Authentication succeeded
Failure - error Credentials validation failed
Response example
response:
{
"msg": "Authentication succeeded."
}
Type : POST
API :
curl -k -X POST -H "Authorization: <AUTH_TOKEN>" -H "Content-Type: application/json" -d '{"username": <USER NAME>, "password": <PASSWORD>}' https://<IP_ADDRESS>/external/authentication/validation
Example :
curl -k -X POST -H "Authorization: 1234b734a9244d54ab8d40aedddcabcd" -H "Content-Type: application/json" -d '{"username": "test", "password": "test"}' https://127.0.0.1/external/authentication/validation
Next steps
For more information, see the Defender for IoT API reference overview .