Skip to content

Users

The resource representing a user in the system.

Endpoints

Skip to section
GET/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

manage

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 eq operator: id, subject, name, email, status, clientId, assignedRoles.id assignedRoles.name, assignedGroups.id, assignedGroupsAssignedRoles.name

Additionally, the following fields support the co operator: name, email, subject

Queries may be rate limited if they differ greatly from these examples:

(id eq "62716ab404a7bd8626af9bd6" or id eq "62716ac4c7e500e13ff5fa22") and (status eq "active" or status eq "disabled")

name co "query" or email co "query" or subject co "query" or id eq "query" or assignedRoles.name eq "query"

Any filters for status must be grouped together and applied to the whole query.

Valid:

(name eq "Bob" or name eq "Alice") and (status eq "active" or status eq "disabled")

Invalid:

name eq "Bob" or name eq "Alice" and (status eq "active" or status eq "disabled")
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.

prev
string

Get users that come before this cursor value when sorted. 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

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 filter parameter to provide an advanced query filter.

endingBefore
deprecated
string

Get users with IDs that are lower than the target user ID. Cannot be used in conjunction with startingAfter. Deprecated. Use prev instead.

role
deprecated
string

The role to filter by. Deprecated.

sortBy
deprecated
default='name'
string

The user parameter to sort by. Deprecated. Use sort instead.

Enum:

name

sortOrder
deprecated
default='asc'
string

The sort order, either ascending or descending. Deprecated. Use sort instead.

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

status
deprecated
default='active'
string

The status to filter by. Supports multiple values delimited by commas. Deprecated. Use the new filter parameter to provide an advanced query filter.

Enum:

active

invited

disabled

deleted

subject
deprecated
PII data
string

The subject to filter by. Deprecated. Use the new filter parameter to provide an advanced query filter.

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

manage

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

manage

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

manage

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

manage

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

manage

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

manage

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.

manage

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

manage

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

managedeprecated

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

object

An 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

object

Error 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

object

The 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

object

Properties

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

object

Data list - ResultItem or ErrorItem for each InviteeItem.

Properties

data
Array<>

No description

InviteErrorItem

object

Error 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

object

Properties

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

object

Properties

invitees

List of invitees who should receive an invite email.

JSONPatch

object

A 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

object
deprecated

An 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

object

Invitee 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

object

A 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 assignedRoles instead.

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

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

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

object

The result object for the user count.

Properties

total
required
number

The total number of users in the tenant.

UserPostSchema

object

Properties

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

object

Properties

data

List of users.

links

Pagination links

v0.879.8
Was this page helpful?