User REST API - v2

NEW IN RELEASE 70

The user REST API allows System Administrators to

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 user details

A user's details can be retrieved by making an HTTP GET request to

GET /api/v2/users/{username}

For example

curl -u admin:admin123 'http://localhost:8070/api/v2/users/bob'

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}

For example

curl -u admin:admin123 -X DELETE 'http://localhost:8070/api/v2/users/bob'

gives

...
HTTP/1.1 204 No Content
...