Endpoints
Skip to sectionGET | /v1/users |
POST | /v1/users |
GET | /v1/users/{userId} |
PATCH | /v1/users/{userId} |
DELETE | /v1/users/{userId} |
GET | /v1/users/actions/count |
POST | /v1/users/actions/filter |
POST | /v1/users/actions/invite |
GET | /v1/users/me |
GET | /v1/users/metadata |
List users
Returns a list of users using cursor-based pagination.
Facts GET /v1/users
Rate limit required | Tier 1 (1000 requests per minute) |
Query Parameters GET /v1/users
fields string | A comma-delimited string of the requested fields per entity. If the 'links' value is omitted, then the entity HATEOAS link will also be omitted. |
filter string | The advanced filtering to use for the query. Refer to RFC 7644 for the syntax. Cannot be combined with any of the fields marked as deprecated. All conditional statements within this query parameter are case insensitive. The following fields support the Additionally, the following fields support the Queries may be rate limited if they differ greatly from these examples:
Any filters for status must be grouped together and applied to the whole query. Valid:
Invalid:
|
limit default=20, minimum=1, maximum=100 number | The number of user entries to retrieve. |
next string | Get users that come after this cursor value when sorted. Cannot be used in conjunction with |
prev string | Get users that come before this cursor value when sorted. Cannot be used in conjunction with |
sort default='+name' string | The field to sort by, with +/- prefix indicating sort order Enum: name +name -name |
totalResults boolean | Whether to return a total match count in the result. Defaults to false. It will trigger an extra DB query to count, reducing the efficiency of the endpoint. |
email deprecated PII data string<email> | The email to filter by. Deprecated. Use the new |
endingBefore deprecated string | Get users with IDs that are lower than the target user ID. Cannot be used in conjunction with startingAfter. Deprecated. Use |
role deprecated string | The role to filter by. Deprecated. |
sortBy deprecated default='name' string | The user parameter to sort by. Deprecated. Use Enum: name |
sortOrder deprecated default='asc' string | The sort order, either ascending or descending. Deprecated. Use Enum: asc desc |
startingAfter deprecated string | Get users with IDs that are higher than the target user ID. Cannot be used in conjunction with endingBefore. Deprecated. Use |
status deprecated default='active' string | The status to filter by. Supports multiple values delimited by commas. Deprecated. Use the new Enum: active invited disabled deleted |
subject deprecated PII data string | The subject to filter by. Deprecated. Use the new |
tenantId deprecated string<uid> | The tenant ID to filter by. Deprecated. |
Responses GET /v1/users
200 application/json | Successful query, returns an array of users |
400 application/json | Invalid request parameters for querying users. |
401 application/json | Not authorized. |
429 application/json | Request has been rate limited. |
500 application/json | Internal server error. |
GET/v1/users
curl "https://your-tenant.us.qlikcloud.com/api/v1/users" \
-H "Authorization: Bearer <API-key>"
Response GET /v1/users
{
"data": [
{
"id": "string",
"name": "string",
"email": "string",
"links": {
"self": {
"href": "http://mytenant.elastic.example/api/v1/users/DKNmFJCNo8SGURUdh2ll--------USER"
}
},
"roles": [],
"locale": "string",
"status": "active",
"created": "2023-11-29T00:09:33.620Z",
"picture": "string",
"subject": "string",
"tenantId": "string",
"zoneinfo": "string",
"createdAt": "2023-11-29T00:09:33.620Z",
"lastUpdated": "2023-11-29T00:09:33.620Z",
"inviteExpiry": 0,
"assignedRoles": [
{
"id": "507f191e810c19729de860ea",
"name": "Developer",
"type": "default",
"level": "user",
"permissions": [
"app:create"
]
}
],
"lastUpdatedAt": "2023-11-29T00:09:33.620Z",
"assignedGroups": [
{
"id": "507f191e810c19729de860eb",
"name": "Finance",
"assignedRoles": [
{
"id": "507f191e810c19729de860ea",
"name": "Developer",
"type": "default",
"level": "user",
"permissions": [
"app:create"
]
}
]
}
],
"preferredLocale": "string",
"preferredZoneinfo": "string"
}
],
"links": {
"next": {
"href": "string"
},
"prev": {
"href": "string"
},
"self": {
"href": "string"
}
}
}
Create user
Creates an invited user.
Facts POST /v1/users
Rate limit required | Tier 2 (100 requests per minute) |
Request Body POST /v1/users
application/json | No description |
Responses POST /v1/users
201 application/json | User created successfully. |
400 application/json | Invalid request was made. |
401 application/json | Unauthorized to create a user. |
403 application/json | Forbidden from creating a user. |
409 application/json | User conflict when attempting to create a new user. |
413 application/json | Payload was too large (limit of 500kB) |
429 application/json | Request has been rate limited. |
500 application/json | Internal server error. |
POST/v1/users
curl "https://your-tenant.us.qlikcloud.com/api/v1/users" \
-X POST \
-H "Authorization: Bearer <API-key>" \
-H "Content-type: application/json" \
-d '{"name":"John Smith","email":"john.smith@corp.example","status":"invited","picture":"https://corp.example/docs/jsmith.png","subject":"1234asdasa6789","tenantId":"q3VRZ4YMixRaLKEPhkZWM-XMIDN7cO8f","assignedRoles":[{"name":"Developer"}]}'
Request POST /v1/users
{
"name": "John Smith",
"email": "john.smith@corp.example",
"status": "invited",
"picture": "https://corp.example/docs/jsmith.png",
"subject": "1234asdasa6789",
"tenantId": "q3VRZ4YMixRaLKEPhkZWM-XMIDN7cO8f",
"assignedRoles": [
{
"name": "Developer"
}
]
}
Response POST /v1/users
{
"id": "string",
"name": "string",
"email": "string",
"links": {
"self": {
"href": "http://mytenant.elastic.example/api/v1/users/DKNmFJCNo8SGURUdh2ll--------USER"
}
},
"roles": [],
"locale": "string",
"status": "active",
"created": "2023-11-29T00:09:33.620Z",
"picture": "string",
"subject": "string",
"tenantId": "string",
"zoneinfo": "string",
"createdAt": "2023-11-29T00:09:33.620Z",
"lastUpdated": "2023-11-29T00:09:33.620Z",
"inviteExpiry": 0,
"assignedRoles": [
{
"id": "507f191e810c19729de860ea",
"name": "Developer",
"type": "default",
"level": "user",
"permissions": [
"app:create"
]
}
],
"lastUpdatedAt": "2023-11-29T00:09:33.620Z",
"assignedGroups": [
{
"id": "507f191e810c19729de860eb",
"name": "Finance",
"assignedRoles": [
{
"id": "507f191e810c19729de860ea",
"name": "Developer",
"type": "default",
"level": "user",
"permissions": [
"app:create"
]
}
]
}
],
"preferredLocale": "string",
"preferredZoneinfo": "string"
}
Get user by ID
Returns the requested user.
Facts GET /v1/users/{userId}
Rate limit required | Tier 1 (1000 requests per minute) |
Path Parameters GET /v1/users/{userId}
userId required string<uid> | The user's unique identifier |
Query Parameters GET /v1/users/{userId}
fields string | A comma-delimited string of the requested fields per entity. If the 'links' value is omitted, then the entity HATEOAS link will also be omitted. |
Responses GET /v1/users/{userId}
200 application/json | User resource |
403 application/json | Forbidden from getting a user. |
404 application/json | User was not found. |
429 application/json | Request has been rate limited. |
500 application/json | Internal server error. |
GET/v1/users/{userId}
curl "https://your-tenant.us.qlikcloud.com/api/v1/users/{userId}" \
-H "Authorization: Bearer <API-key>"
Response GET /v1/users/{userId}
{
"id": "string",
"name": "string",
"email": "string",
"links": {
"self": {
"href": "http://mytenant.elastic.example/api/v1/users/DKNmFJCNo8SGURUdh2ll--------USER"
}
},
"roles": [],
"locale": "string",
"status": "active",
"created": "2023-11-29T00:09:33.620Z",
"picture": "string",
"subject": "string",
"tenantId": "string",
"zoneinfo": "string",
"createdAt": "2023-11-29T00:09:33.620Z",
"lastUpdated": "2023-11-29T00:09:33.620Z",
"inviteExpiry": 0,
"assignedRoles": [
{
"id": "507f191e810c19729de860ea",
"name": "Developer",
"type": "default",
"level": "user",
"permissions": [
"app:create"
]
}
],
"lastUpdatedAt": "2023-11-29T00:09:33.620Z",
"assignedGroups": [
{
"id": "507f191e810c19729de860eb",
"name": "Finance",
"assignedRoles": [
{
"id": "507f191e810c19729de860ea",
"name": "Developer",
"type": "default",
"level": "user",
"permissions": [
"app:create"
]
}
]
}
],
"preferredLocale": "string",
"preferredZoneinfo": "string"
}
Update user by ID
Updates fields for a user resource
Facts PATCH /v1/users/{userId}
Rate limit required | Tier 2 (100 requests per minute) |
Path Parameters PATCH /v1/users/{userId}
userId required string<uid> | The ID of the user to update. |
Request Body PATCH /v1/users/{userId}
application/json | No description |
Responses PATCH /v1/users/{userId}
204 application/json object | User updated successfully. |
207 application/json | User update was partially successful with non-critical failures. |
400 application/json | Invalid request for patching a user. |
403 application/json | Forbidden from patching a user. |
404 application/json | User was not found. |
429 application/json | Request has been rate limited. |
PATCH/v1/users/{userId}
curl "https://your-tenant.us.qlikcloud.com/api/v1/users/{userId}" \
-X PATCH \
-H "Authorization: Bearer <API-key>" \
-H "Content-type: application/json" \
-d '[{"op":"replace","path":"/name","value":"John"},{"op":"replace","path":"/assignedRoles","value":[{"name":"Developer"}]},{"op":"replace","path":"/email","value":"unicorn@corp.example"},{"op":"replace","path":"/preferredZoneInfo","value":"America/Halifax"},{"op":"replace","path":"/preferredLocale","value":"en_US_POSIX"},{"op":"replace","path":"/status","value":"active"}]'
Request PATCH /v1/users/{userId}
[
{
"op": "replace",
"path": "/name",
"value": "John"
},
{
"op": "replace",
"path": "/assignedRoles",
"value": [
{
"name": "Developer"
}
]
},
{
"op": "replace",
"path": "/email",
"value": "unicorn@corp.example"
},
{
"op": "replace",
"path": "/preferredZoneInfo",
"value": "America/Halifax"
},
{
"op": "replace",
"path": "/preferredLocale",
"value": "en_US_POSIX"
},
{
"op": "replace",
"path": "/status",
"value": "active"
}
]
Response PATCH /v1/users/{userId}
{
"errors": [
{
"code": "USERS-7",
"title": "Not found",
"status": 404
}
],
"traceId": "000000000000000079cf1ebeae103de1"
}
Delete user by ID
Deletes the requested user.
Facts DELETE /v1/users/{userId}
Rate limit required | Tier 2 (100 requests per minute) |
Path Parameters DELETE /v1/users/{userId}
userId required string<uid> | The ID of the user to delete. |
Responses DELETE /v1/users/{userId}
204 application/json object | User deleted successfully. |
400 application/json | Invalid request for deleting a user. |
403 application/json | Forbidden from deleting a user. |
404 application/json | User was not found. |
429 application/json | Request has been rate limited. |
DELETE/v1/users/{userId}
curl "https://your-tenant.us.qlikcloud.com/api/v1/users/{userId}" \
-X DELETE \
-H "Authorization: Bearer <API-key>"
Count users
Returns the number of users in a given tenant
Facts GET /v1/users/actions/count
Rate limit required | Tier 1 (1000 requests per minute) |
Query Parameters GET /v1/users/actions/count
tenantId deprecated string<uid> | The tenant ID to filter by. |
Responses GET /v1/users/actions/count
200 application/json | The count of users. |
403 application/json | Forbidden from reading the count. |
404 application/json | Not found. |
429 application/json | Request has been rate limited. |
GET/v1/users/actions/count
curl "https://your-tenant.us.qlikcloud.com/api/v1/users/actions/count" \
-H "Authorization: Bearer <API-key>"
Response GET /v1/users/actions/count
{
"total": 0
}
Filter users
Retrieves a list of users matching the filter using an advanced query string.
Facts POST /v1/users/actions/filter
Rate limit required | Special (200 requests per minute) |
Query Parameters POST /v1/users/actions/filter
fields string | A comma-delimited string of the requested fields per entity. If the 'links' value is omitted, then the entity HATEOAS link will also be omitted. |
limit default=20, minimum=1, maximum=100 number | The number of user entries to retrieve. |
next string | Get users with IDs that are higher than the target user ID. Cannot be used in conjunction with prev. |
prev string | Get users with IDs that are lower than the target user ID. Cannot be used in conjunction with next. |
sort default='+name' string | The field to sort by, with +/- prefix indicating sort order Enum: name +name -name |
Request Body POST /v1/users/actions/filter
application/json | Will contain the query filter to apply. It shall not contain more than 100 ids. |
Responses POST /v1/users/actions/filter
200 application/json | Users retrieved. |
400 application/json | Advanced query filter syntax error or query params format error or filter too complex. |
401 application/json | Unauthorized, JWT invalid or not provided. |
403 application/json | The operation failed due to unsufficient permissions. |
429 application/json | Request has been rate limited. |
500 application/json | Internal server error. |
POST/v1/users/actions/filter
curl "https://your-tenant.us.qlikcloud.com/api/v1/users/actions/filter" \
-X POST \
-H "Authorization: Bearer <API-key>" \
-H "Content-type: application/json" \
-d '{"filter":"(id eq \"626949b9017b657805080bbd\" or id eq \"626949bf017b657805080bbe\") and (status eq \"active\" or status eq \"deleted\")"}'
Request POST /v1/users/actions/filter
{
"filter": "(id eq \"626949b9017b657805080bbd\" or id eq \"626949bf017b657805080bbe\") and (status eq \"active\" or status eq \"deleted\")"
}
Response POST /v1/users/actions/filter
{
"data": [
{
"id": "string",
"name": "string",
"email": "string",
"links": {
"self": {
"href": "http://mytenant.elastic.example/api/v1/users/DKNmFJCNo8SGURUdh2ll--------USER"
}
},
"roles": [],
"locale": "string",
"status": "active",
"created": "2023-11-29T00:09:33.621Z",
"picture": "string",
"subject": "string",
"tenantId": "string",
"zoneinfo": "string",
"createdAt": "2023-11-29T00:09:33.621Z",
"lastUpdated": "2023-11-29T00:09:33.621Z",
"inviteExpiry": 0,
"assignedRoles": [
{
"id": "507f191e810c19729de860ea",
"name": "Developer",
"type": "default",
"level": "user",
"permissions": [
"app:create"
]
}
],
"lastUpdatedAt": "2023-11-29T00:09:33.621Z",
"assignedGroups": [
{
"id": "507f191e810c19729de860eb",
"name": "Finance",
"assignedRoles": [
{
"id": "507f191e810c19729de860ea",
"name": "Developer",
"type": "default",
"level": "user",
"permissions": [
"app:create"
]
}
]
}
],
"preferredLocale": "string",
"preferredZoneinfo": "string"
}
],
"links": {
"next": {
"href": "string"
},
"prev": {
"href": "string"
},
"self": {
"href": "string"
}
}
}
Invite one or more users by email address.
Facts POST /v1/users/actions/invite
Rate limit required | Tier 2 (100 requests per minute) |
Request Body POST /v1/users/actions/invite
application/json | No description |
Responses POST /v1/users/actions/invite
207 application/json | Request completed successfully. See Results for ResultDetail on each invite. |
403 application/json | Request denied. |
default application/json | Request error. See Errors. |
POST/v1/users/actions/invite
curl "https://your-tenant.us.qlikcloud.com/api/v1/users/actions/invite" \
-X POST \
-H "Authorization: Bearer <API-key>" \
-H "Content-type: application/json" \
-d '{"invitees":[{"name":"string","email":"string","resend":true,"language":"string"}]}'
Request POST /v1/users/actions/invite
{
"invitees": [
{
"name": "string",
"email": "string",
"resend": true,
"language": "string"
}
]
}
Response POST /v1/users/actions/invite
{
"data": []
}
Get my user
Redirects to retrieve the user resource associated with the JWT claims.
Facts GET /v1/users/me
Rate limit required | Tier 1 (1000 requests per minute) |
Responses GET /v1/users/me
301 text/html string | Successful redirect. |
429 application/json | Request has been rate limited. |
GET/v1/users/me
curl "https://your-tenant.us.qlikcloud.com/api/v1/users/me" \
-H "Authorization: Bearer <API-key>"
Get configuration metadata
Returns the metadata with regard to the user configuration. Deprecated, use GET /v1/roles instead.
Facts GET /v1/users/metadata
Rate limit required | Tier 1 (1000 requests per minute) |
Responses GET /v1/users/metadata
200 application/json | User configuration |
401 application/json | Unauthorized. |
429 application/json | Request has been rate limited. |
500 application/json | Internal server error. |
GET/v1/users/metadata
curl "https://your-tenant.us.qlikcloud.com/api/v1/users/metadata" \
-H "Authorization: Bearer <API-key>"
Response GET /v1/users/metadata
{
"valid_roles": [
"TenantAdmin",
"Developer"
]
}
AssignedGroups
Array<object>An array of group references.
Properties
id required string<uuid> | The unique group identitier |
name required string | The group name |
assignedRoles | An array of role references. |
AssignedRoles
Array<object>An array of role references.
Properties
id required string<uuid> | The unique role identitier |
name required filterable string | The role name |
type required string | The type of role Enum: default |
level required string | The role level Enum: admin user |
permissions required Array<string> | An array of permissions associated to a given role. |
AssignedRolesRefIDs
Array<object>An array of role reference identifiers.
Properties
id required string<uuid> | The unique role identitier |
AssignedRolesRefNames
Array<name>An array of role reference names.
Properties
name required string | The name of the role |
Error
objectAn error object describing the error.
Properties
code required string | The error code. |
meta object | Additional properties relating to the error. |
title required string | Summary of the problem. |
detail string | A human-readable explanation specific to this occurrence of the problem. |
source | References to the source of the error. |
status number | The HTTP status code. |
ErrorItem
objectError object.
Properties
code required integer | Error code |
title required string | Summary of the problem |
detail string | A human-readable explanation specific to this occurrence of the problem (if applicable) |
Errors
objectThe error response object describing the error from the handling of an HTTP request.
Properties
errors | An array of errors related to the operation. |
traceId string | A unique identifier for tracing the error. |
ErrorsResponse
objectProperties
errors | No description |
Filter
An advanced query filter to be used for complex user querying in the tenant.
Properties
filter string | The advanced filtering to be applied the query. All conditional statements within this query parameter are case insensitive. |
InviteDataResponse
objectData list - ResultItem or ErrorItem for each InviteeItem.
Properties
data Array<> | No description |
InviteErrorItem
objectError object.
Properties
code string | Error code - | HTTP Status code | 1001 - Active User | 1002 - Disabled User | 1003 - Default External Dependency Error | |
title required string | Summary of the problem |
detail string | A human-readable explanation specific to this occurrence of the problem (if applicable) |
email required PII data string | Invitee email |
status required string | Result status = "error" Enum: error |
InviteItem
objectProperties
name PII data string | Optional display name for this invitee. Example - "Elvis Presley". |
email required PII data string | Email address for this invitee. Example - "foo@qlik.com". |
resend boolean | Flag - when true invite message is sent to inactive or invited users. Typically used to force email resend to users who are not yet active. |
language string | Optional ISO 639-1 2 letter code for invite language. Defaults to 'en' when missing or not found. |
InviteRequest
objectProperties
invitees | List of invitees who should receive an invite email. |
JSONPatch
objectA JSON Patch document as defined in http://tools.ietf.org/html/rfc6902.
Properties
op required string | The operation to be performed. Enum: replace set (Deprecated) unset (Deprecated) add (Deprecated) renew |
path required string | A JSON Pointer. Enum: /name /roles (Deprecated) /assignedRoles /inviteExpiry /preferredZoneinfo /preferredLocale /status |
value required | The value to be used for this operation. |
JSONPatchArray
Array<JSONPatch>An array of JSON Patch documents
Properties
op required string | The operation to be performed. Enum: replace set (Deprecated) unset (Deprecated) add (Deprecated) renew |
path required string | A JSON Pointer. Enum: /name /roles (Deprecated) /assignedRoles /inviteExpiry /preferredZoneinfo /preferredLocale /status |
value required | The value to be used for this operation. |
Metadata
objectAn object containing the metadata for the user configuration.
Properties
valid_roles Array<string> | List of system roles to which the user can be assigned. |
ResultItem
objectInvitee result item
Properties
email required PII data string | Email specified for this invitee |
status required string | Result status = {"ok" (new user; email sent) | "exists" (existing user; no email sent)} Enum: ok exists |
userId required string<uid> | UserId for this invitee |
subject required PII data string<uuid> | IdP generated UUID for this invitee |
User
objectA user object.
Properties
id required filterable string<uid> | The unique user identifier. |
name required filterable PII data string | The name of the user. |
email filterable PII data string | The email address for the user. |
links | Pagination links to the user. |
roles deprecated Array<string> | List of system roles to which the user has been assigned. Only returned when permitted by access control. Deprecated. Use |
locale string | Represents the end-user's language tag. |
status filterable string | The status of the user within the tenant. Enum: active invited disabled deleted |
created deprecated string<date> | Deprecated. Use |
picture PII data string<url> | A static url linking to the avatar of the user. |
subject required filterable PII data string | The unique user identitier from an identity provider. |
tenantId required string<uid> | The tenant that the user belongs too. |
zoneinfo string | Represents the end-user's time zone. |
createdAt string<date-time> | The timestamp for when the user record was created. |
lastUpdated deprecated string<date> | Deprecated. Use |
inviteExpiry number | The number of seconds until the user invitation will expire. |
assignedRoles | An array of role references. |
lastUpdatedAt string<date-time> | The timestamp for when the user record was last updated. |
assignedGroups | An array of group references. |
preferredLocale string | Represents the end-user's preferred language tag. |
preferredZoneinfo string | Represents the end-user's preferred time zone. |
UserCount
objectThe result object for the user count.
Properties
total required number | The total number of users in the tenant. |
UserPostSchema
objectProperties
name PII data string | The name of the user. |
email PII data string | The email address for the user. This is a required field when inviting a user. |
roles deprecated Array<string> | List of system roles to which the user has been assigned. Only returned when permitted by access control. |
status string | The status of the created user within the tenant. Enum: invited |
picture PII data string<url> | A static url linking to the avatar of the user. |
subject required PII data string | The unique user identitier from an identity provider. |
tenantId string<uid> | The tenant that the user will belong too. |
assignedRoles | The roles to assign to the user. |
Users
objectProperties
data | List of users. |
links | Pagination links |