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
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
Tier 1 (1000 requests per minute)

Query Parameters GET /v1/users

fields
optional
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
optional
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
optional, default=20, minimum=1, maximum=100
number

The number of user entries to retrieve.

next
optional
string

Get users that come after this cursor value when sorted. Cannot be used in conjunction with prev.

prev
optional
string

Get users that come before this cursor value when sorted. Cannot be used in conjunction with next.

sort
optional, default='+name'
string

The field to sort by, with +/- prefix indicating sort order

Enum:

name

+name

-name

email
deprecated
optional
string<email>

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

endingBefore
deprecated
optional
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
optional
string

The role to filter by. Deprecated.

sortBy
deprecated
optional, default='name'
string

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

Enum:

name

sortOrder
deprecated
optional, default='asc'
string

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

Enum:

asc

desc

startingAfter
deprecated
optional
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
optional, 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
optional
string

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

tenantId
deprecated
optional
string<uid>

The tenant ID to filter by. Deprecated.

Responses GET /v1/users

200
optional, application/json

Successful query, returns an array of users

400
optional, application/json

Invalid request parameters for querying users.

401
optional, application/json

Not authorized.

429
optional, application/json

Request has been rate limited.

500
optional, 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": "2022-11-22T14:26:39.437Z",
      "picture": "string",
      "subject": "string",
      "tenantId": "string",
      "zoneinfo": "string",
      "createdAt": "2022-11-22T14:26:39.437Z",
      "lastUpdated": "2022-11-22T14:26:39.437Z",
      "inviteExpiry": 0,
      "assignedRoles": [
        {
          "id": "507f191e810c19729de860ea",
          "name": "Developer",
          "type": "default",
          "level": "user",
          "permissions": [
            "app:create"
          ]
        }
      ],
      "lastUpdatedAt": "2022-11-22T14:26:39.437Z",
      "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
Tier 2 (100 requests per minute)

Request Body POST /v1/users

application/json

No description

Responses POST /v1/users

201
optional, application/json

User created successfully.

400
optional, application/json

Invalid request was made.

401
optional, application/json

Unauthorized to create a user.

403
optional, application/json

Forbidden from creating a user.

409
optional, application/json

User conflict when attempting to create a new user.

413
optional, application/json

Payload was too large (limit of 500kB)

429
optional, application/json

Request has been rate limited.

500
optional, 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":[{"id":"507f191e810c19729de860ea"}]}'

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": [
    {
      "id": "507f191e810c19729de860ea"
    }
  ]
}

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": "2022-11-22T14:26:39.437Z",
  "picture": "string",
  "subject": "string",
  "tenantId": "string",
  "zoneinfo": "string",
  "createdAt": "2022-11-22T14:26:39.437Z",
  "lastUpdated": "2022-11-22T14:26:39.437Z",
  "inviteExpiry": 0,
  "assignedRoles": [
    {
      "id": "507f191e810c19729de860ea",
      "name": "Developer",
      "type": "default",
      "level": "user",
      "permissions": [
        "app:create"
      ]
    }
  ],
  "lastUpdatedAt": "2022-11-22T14:26:39.437Z",
  "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
Tier 1 (1000 requests per minute)

Path Parameters GET /v1/users/{userId}

userId
string<uid>

The user's unique identifier

Responses GET /v1/users/{userId}

200
optional, application/json

User resource

403
optional, application/json

Forbidden from getting a user.

404
optional, application/json

User was not found.

429
optional, application/json

Request has been rate limited.

500
optional, 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": "2022-11-22T14:26:39.437Z",
  "picture": "string",
  "subject": "string",
  "tenantId": "string",
  "zoneinfo": "string",
  "createdAt": "2022-11-22T14:26:39.437Z",
  "lastUpdated": "2022-11-22T14:26:39.437Z",
  "inviteExpiry": 0,
  "assignedRoles": [
    {
      "id": "507f191e810c19729de860ea",
      "name": "Developer",
      "type": "default",
      "level": "user",
      "permissions": [
        "app:create"
      ]
    }
  ],
  "lastUpdatedAt": "2022-11-22T14:26:39.437Z",
  "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
Tier 2 (100 requests per minute)

Path Parameters PATCH /v1/users/{userId}

userId
string<uid>

The ID of the user to update.

Request Body PATCH /v1/users/{userId}

optional, application/json

No description

Responses PATCH /v1/users/{userId}

204
optional, application/json
object

User updated successfully.

207
optional, application/json

User update was partially successful with non-critical failures.

400
optional, application/json

Invalid request for patching a user.

403
optional, application/json

Forbidden from patching a user.

404
optional, application/json

User was not found.

429
optional, 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":[{"id":"507f191e810c19729de860ea"}]},{"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": [
      {
        "id": "507f191e810c19729de860ea"
      }
    ]
  },
  {
    "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
Tier 2 (100 requests per minute)

Path Parameters DELETE /v1/users/{userId}

userId
string<uid>

The ID of the user to delete.

Responses DELETE /v1/users/{userId}

204
optional, application/json
object

User deleted successfully.

400
optional, application/json

Invalid request for deleting a user.

403
optional, application/json

Forbidden from deleting a user.

404
optional, application/json

User was not found.

429
optional, 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
Tier 1 (1000 requests per minute)

Query Parameters GET /v1/users/actions/count

tenantId
deprecated
optional
string<uid>

The tenant ID to filter by.

Responses GET /v1/users/actions/count

200
optional, application/json

The count of users.

403
optional, application/json

Forbidden from reading the count.

404
optional, application/json

Not found.

429
optional, 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
Tier 2 (100 requests per minute)

Query Parameters POST /v1/users/actions/filter

fields
optional
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
optional, default=20, minimum=1, maximum=100
number

The number of user entries to retrieve.

next
optional
string

Get users with IDs that are higher than the target user ID. Cannot be used in conjunction with prev.

prev
optional
string

Get users with IDs that are lower than the target user ID. Cannot be used in conjunction with next.

sort
optional, default='+name'
string

The field to sort by, with +/- prefix indicating sort order

Enum:

name

+name

-name

Request Body POST /v1/users/actions/filter

optional, application/json

Will contain the query filter to apply. It shall not contain more than 50 ids.

Responses POST /v1/users/actions/filter

200
optional, application/json

Users retrieved.

400
optional, application/json

Advanced query filter syntax error or query params format error or filter too complex.

401
optional, application/json

Unauthorized, JWT invalid or not provided.

403
optional, application/json

The operation failed due to unsufficient permissions.

429
optional, application/json

Request has been rate limited.

500
optional, 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": "2022-11-22T14:26:39.437Z",
      "picture": "string",
      "subject": "string",
      "tenantId": "string",
      "zoneinfo": "string",
      "createdAt": "2022-11-22T14:26:39.437Z",
      "lastUpdated": "2022-11-22T14:26:39.437Z",
      "inviteExpiry": 0,
      "assignedRoles": [
        {
          "id": "507f191e810c19729de860ea",
          "name": "Developer",
          "type": "default",
          "level": "user",
          "permissions": [
            "app:create"
          ]
        }
      ],
      "lastUpdatedAt": "2022-11-22T14:26:39.437Z",
      "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"
    }
  }
}

Get my user

manage

Redirects to retrieve the user resource associated with the JWT claims.

Facts GET /v1/users/me

Rate limit
Tier 1 (1000 requests per minute)

Responses GET /v1/users/me

301
optional, text/html
string

Successful redirect.

429
optional, 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
Tier 1 (1000 requests per minute)

Responses GET /v1/users/metadata

200
optional, application/json

User configuration

401
optional, application/json

Unauthorized.

429
optional, application/json

Request has been rate limited.

500
optional, 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
string<uuid>

The unique group identitier

name
string

The group name

assignedRoles
optional

An array of role references.

AssignedRoles

Array<object>

An array of role references.

Properties

id
string<uuid>

The unique role identitier

name
string

The role name

type
string

The type of role

Enum:

default

level
string

The role level

Enum:

admin

user

permissions
Array<string>

An array of permissions associated to a given role.

AssignedRolesRefIDs

Array<object>

An array of role reference identifiers.

Properties

id
string<uuid>

The unique role identitier

Error

object

An error object describing the error.

Properties

code
string

The error code.

meta
optional
object

Additional properties relating to the error.

title
string

Summary of the problem.

detail
optional
string

A human-readable explanation specific to this occurrence of the problem.

source
optional

References to the source of the error.

status
optional
number

The HTTP status code.

Errors

object

The error response object describing the error from the handling of an HTTP request.

Properties

errors
optional

An array of errors related to the operation.

traceId
optional
string

A unique identifier for tracing the error.

Filter

An advanced query filter to be used for complex user querying in the tenant.

Properties

filter
optional
string

The advanced filtering to be applied the query. All conditional statements within this query parameter are case insensitive.

JSONPatch

object

A JSON Patch document as defined in http://tools.ietf.org/html/rfc6902.

Properties

op
string

The operation to be performed.

Enum:

replace

set (Deprecated)

unset (Deprecated)

add (Deprecated)

renew

path
string

A JSON Pointer.

Enum:

/name

/roles (Deprecated)

/assignedRoles

/inviteExpiry

/preferredZoneinfo

/preferredLocale

/status

value

The value to be used for this operation.

JSONPatchArray

Array<JSONPatch>

An array of JSON Patch documents

Properties

op
string

The operation to be performed.

Enum:

replace

set (Deprecated)

unset (Deprecated)

add (Deprecated)

renew

path
string

A JSON Pointer.

Enum:

/name

/roles (Deprecated)

/assignedRoles

/inviteExpiry

/preferredZoneinfo

/preferredLocale

/status

value

The value to be used for this operation.

Metadata

object
deprecated

An object containing the metadata for the user configuration.

Properties

valid_roles
optional
Array<string>

List of system roles to which the user can be assigned.

User

object

A user object.

Properties

id
string<uid>

The unique user identifier.

name
string

The name of the user.

email
optional
string

The email address for the user.

links
optional

Pagination links to the user.

roles
deprecated
optional
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
optional
string

Represents the end-user's language tag.

status
optional
string

The status of the user within the tenant.

Enum:

active

invited

disabled

deleted

created
deprecated
optional
string<date>

Deprecated. Use createdAt instead.

picture
optional
string<url>

A static url linking to the avatar of the user.

subject
string

The unique user identitier from an identity provider.

tenantId
string<uid>

The tenant that the user belongs too.

zoneinfo
optional
string

Represents the end-user's time zone.

createdAt
optional
string<date-time>

The timestamp for when the user record was created.

lastUpdated
deprecated
optional
string<date>

Deprecated. Use lastUpdatedAt instead.

inviteExpiry
optional
number

The number of seconds until the user invitation will expire.

assignedRoles
optional

An array of role references.

lastUpdatedAt
optional
string<date-time>

The timestamp for when the user record was last updated.

assignedGroups
optional

An array of group references.

preferredLocale
optional
string

Represents the end-user's preferred language tag.

preferredZoneinfo
optional
string

Represents the end-user's preferred time zone.

UserCount

object

The result object for the user count.

Properties

total
number

The total number of users in the tenant.

UserPostSchema

object

Properties

name
optional
string

The name of the user.

email
optional
string

The email address for the user. This is a required field when inviting a user.

roles
deprecated
optional
Array<string>

List of system roles to which the user has been assigned. Only returned when permitted by access control.

status
optional
string

The status of the created user within the tenant.

Enum:

invited

picture
optional
string<url>

A static url linking to the avatar of the user.

subject
string

The unique user identitier from an identity provider.

tenantId
optional
string<uid>

The tenant that the user will belong too.

assignedRoles
optional

An array of role reference identifiers.

Users

object

Properties

data
optional

List of users.

links
optional

Pagination links

v0.509.8
Was this page helpful?