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
...