User REST API - v2
The user REST API allows System Administrators to do the following:
If enabled, the audit log will record creating/updating/deleting users.
In the following sections, all partial URLs are relative to IQ Server's base URL and we issue requests using the cURL
tool. Also, all request/response bodies are JSON content (formatted here for readability) and any endpoints that return a user's details exclude their password for security.
Get all user details
All user details can be retrieved by making an HTTP GET request to
GET /api/v2/users
NEW IN RELEASE 136
An optional "realm" query parameter can be added to retrieve all user details for users belonging to the given security realm. If omitted, the realm will default to be the Internal realm. Supported values include "Internal" and "SAML".
For example
curl -u admin:admin123 http://localhost:8070/api/v2/users?realm=Internal
gives
{ "users": [ { "username": "admin", "firstName": "Admin", "lastName": "BuiltIn", "email": "admin@localhost" }, { "username": "bob", "firstName": "Bob", "lastName": "Smith", "email": "bobsmith@domain.com" } ] }
Get user details
A user's details can be retrieved by making an HTTP GET request to
GET /api/v2/users/{username}
NEW IN RELEASE 136
An optional "realm" query parameter can be added to retrieve a user's details in the given security realm. If omitted, the realm will default to be the Internal realm. Supported values include "Internal" and "SAML".
For example
curl -u admin:admin123 'http://localhost:8070/api/v2/users/bob?realm=Internal'
gives
{ "username": "bob", "firstName": "Bob", "lastName": "Smith", "email": "bobsmith@domain.com" }
Create users
A user can be created by making an HTTP POST request to
POST /api/v2/users
with a body specifying the user's details.
For example, using the body
{ "username": "ted", "password": "secret", "firstName": "Ted", "lastName": "Baker", "email": "tedbaker@example.com" }
Note that all of these fields are required.
curl -u admin:admin123 -X POST -H 'Content-Type: application/json' 'http://localhost:8070/api/v2/users' -d '{"username": "ted","password": "secret","firstName": "Ted","lastName": "Baker","email": "tedbaker@example.com"}'
gives
... HTTP/1.1 204 No Content ...
Update users
A user can be updated by making an HTTP PUT request to
PUT /api/v2/users/{username}
with a body specifying the user's details.
For example, using the body
{ "firstName": "Teddy", "lastName": "Norman", "email": "tnorman@example.com" }
Note that only the "username" in the path is required, any unspecified fields will remain unchanged. If a "username" is also provided in the body, then it must match that in the path.
Also, note that a user's "username" and/or "password" cannot be updated this way.
curl -u admin:admin123 -X PUT -H 'Content-Type: application/json' 'http://localhost:8070/api/v2/users/ted' -d '{"firstName": "Teddy","lastName": "Norman","email": "tnorman@example.com"}'
gives
{ "username": "ted", "firstName": "Teddy", "lastName": "Norman", "email": "tnorman@example.com" }
An example of a partial update would be
curl -u admin:admin123 -X PUT -H 'Content-Type: application/json' 'http://localhost:8070/api/v2/users/ted' -d '{"email": "tnorman@new.com"}'
which gives
{ "username": "ted", "firstName": "Teddy", "lastName": "Norman", "email": "tnorman@new.com" }
Delete users
A user can be deleted by making an HTTP DELETE request to
DELETE /api/v2/users/{username}
NEW IN RELEASE 136
An optional "realm" query parameter can be added to delete a user from the given security realm. If omitted, the realm will default to be the Internal realm. Supported values include "Internal" and "SAML".
For example
curl -u admin:admin123 -X DELETE 'http://localhost:8070/api/v2/users/bob?realm=Internal'
gives
... HTTP/1.1 204 No Content ...