openapi: 3.1.0
info:
title: ThingsBoard Admin admin-controller user-controller API
description: 'ThingsBoard Admin API — subset of the ThingsBoard REST API (open-source IoT platform). Covers: Admin, Audit Log, Event, Usage Info, Queue, Queue Stats, Mail Config Template, Qr Code Settings, Job.'
version: 4.3.0.3DEMO
contact:
name: ThingsBoard team
url: https://thingsboard.io
email: info@thingsboard.io
license:
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0
servers:
- url: https://demo.thingsboard.io
description: ThingsBoard Live Demo
- url: http://localhost:8080
description: Local ThingsBoard server
tags:
- name: user-controller
description: User
paths:
/api/user/settings:
get:
tags:
- user-controller
summary: Get User Settings (getUserSettings)
description: 'Fetch the User settings based on authorized user. '
operationId: getUserSettings
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/JsonNode'
put:
tags:
- user-controller
summary: Update User Settings (saveUserSettings)
description: 'Update user settings for authorized user. Only specified json elements will be updated.Example: you have such settings: {A:5, B:{C:10, D:20}}. Updating it with {B:{C:10, D:30}} will result in{A:5, B:{C:10, D:30}}. The same could be achieved by putting {B.D:30}'
operationId: putUserSettings
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/JsonNode'
required: true
responses:
'200':
description: OK
post:
tags:
- user-controller
summary: Save User Settings (saveUserSettings)
description: 'Save user settings represented in json format for authorized user. '
operationId: saveUserSettings
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/JsonNode'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/JsonNode'
/api/user/settings/{type}:
get:
tags:
- user-controller
summary: Get User Settings (getUserSettings)
description: 'Fetch the User settings based on authorized user. '
operationId: getUserSettings_1
parameters:
- name: type
in: path
description: 'Settings type, case insensitive, one of: "general", "quick_links", "doc_links" or "dashboards".'
required: true
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/JsonNode'
put:
tags:
- user-controller
summary: Update User Settings (saveUserSettings)
description: 'Update user settings for authorized user. Only specified json elements will be updated.Example: you have such settings: {A:5, B:{C:10, D:20}}. Updating it with {B:{C:10, D:30}} will result in{A:5, B:{C:10, D:30}}. The same could be achieved by putting {B.D:30}'
operationId: putUserSettings_1
parameters:
- name: type
in: path
description: 'Settings type, case insensitive, one of: "general", "quick_links", "doc_links" or "dashboards".'
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/JsonNode'
required: true
responses:
'200':
description: OK
/api/user:
post:
tags:
- user-controller
summary: Save or Update User (saveUser)
description: 'Create or update the User. When creating user, platform generates User Id as [time-based UUID](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_1_(date-time_and_MAC_address)). The newly created User Id will be present in the response. Specify existing User Id to update the device. Referencing non-existing User Id will cause ''Not Found'' error.
Device email is unique for entire platform setup.Remove ''id'', ''tenantId'' and optionally ''customerId'' from the request body example (below) to create new User entity.
Available for users with ''SYS_ADMIN'', ''TENANT_ADMIN'' or ''CUSTOMER_USER'' authority.'
operationId: saveUser
parameters:
- name: sendActivationMail
in: query
description: Send activation email (or use activation link)
required: false
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/User'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/User'
/api/user/{userId}/userCredentialsEnabled:
post:
tags:
- user-controller
summary: Enable/Disable User Credentials (setUserCredentialsEnabled)
description: "Enables or Disables user credentials. Useful when you would like to block user account without deleting it. You can specify parameters to filter the results. The result is wrapped with PageData object that allows you to iterate over result set using pagination. See response schema for more details. \n\nAvailable for users with 'TENANT_ADMIN' authority."
operationId: setUserCredentialsEnabled
parameters:
- name: userId
in: path
description: A string value representing the user id. For example, '784f394c-42b6-435a-983c-b7beff2784f9'
required: true
schema:
type: string
- name: userCredentialsEnabled
in: query
description: Enable ("true") or disable ("false") the credentials.
required: false
schema:
type: string
responses:
'200':
description: OK
/api/user/sendActivationMail:
post:
tags:
- user-controller
summary: Send or Re-send the Activation Email
description: "Force send the activation email to the user. Useful to resend the email if user has accidentally deleted it. \n\nAvailable for users with 'SYS_ADMIN' or 'TENANT_ADMIN' authority."
operationId: sendActivationEmail
parameters:
- name: email
in: query
description: Email of the user
required: true
schema:
type: string
responses:
'200':
description: OK
/api/user/mobile/session:
get:
tags:
- user-controller
operationId: getMobileSession
parameters:
- name: X-Mobile-Token
in: header
required: true
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/MobileSessionInfo'
post:
tags:
- user-controller
operationId: saveMobileSession
parameters:
- name: X-Mobile-Token
in: header
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/MobileSessionInfo'
required: true
responses:
'200':
description: OK
delete:
tags:
- user-controller
operationId: removeMobileSession
parameters:
- name: X-Mobile-Token
in: header
required: true
schema:
type: string
responses:
'200':
description: OK
/api/users:
get:
tags:
- user-controller
summary: Get Users (getUsers)
description: "Returns a page of users owned by tenant or customer. The scope depends on authority of the user that performs the request.You can specify parameters to filter the results. The result is wrapped with PageData object that allows you to iterate over result set using pagination. See response schema for more details. \n\nAvailable for users with 'TENANT_ADMIN' or 'CUSTOMER_USER' authority."
operationId: getUsersByIds
parameters:
- name: userIds
in: query
description: A list of user ids, separated by comma ','
required: true
schema:
type: array
items:
type: string
- name: pageSize
in: query
description: Maximum amount of entities in a one page
required: true
schema:
type: integer
format: int32
- name: page
in: query
description: Sequence number of page starting from 0
required: true
schema:
type: integer
format: int32
- name: textSearch
in: query
description: The case insensitive 'substring' filter based on the user email.
required: false
schema:
type: string
- name: sortProperty
in: query
description: Property of entity to sort by
required: false
schema:
type: string
enum:
- createdTime
- firstName
- lastName
- email
- name: sortOrder
in: query
description: Sort order. ASC (ASCENDING) or DESC (DESCENDING)
required: false
schema:
type: string
enum:
- ASC
- DESC
responses:
'200':
description: OK
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/PageDataUser'
- type: array
items:
$ref: '#/components/schemas/User'
/api/users/info:
get:
tags:
- user-controller
summary: Find Users by Query (findUsersByQuery)
description: "Returns page of user data objects. Search is been executed by email, firstName and lastName fields. You can specify parameters to filter the results. The result is wrapped with PageData object that allows you to iterate over result set using pagination. See response schema for more details. \n\nAvailable for users with 'TENANT_ADMIN' or 'CUSTOMER_USER' authority."
operationId: findUsersByQuery
parameters:
- name: pageSize
in: query
description: Maximum amount of entities in a one page
required: true
schema:
type: integer
format: int32
- name: page
in: query
description: Sequence number of page starting from 0
required: true
schema:
type: integer
format: int32
- name: textSearch
in: query
description: The case insensitive 'substring' filter based on the user email.
required: false
schema:
type: string
- name: sortProperty
in: query
description: Property of entity to sort by
required: false
schema:
type: string
enum:
- createdTime
- firstName
- lastName
- email
- name: sortOrder
in: query
description: Sort order. ASC (ASCENDING) or DESC (DESCENDING)
required: false
schema:
type: string
enum:
- ASC
- DESC
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/PageDataUserEmailInfo'
/api/users/assign/{alarmId}:
get:
tags:
- user-controller
summary: Get UsersForAssign (getUsersForAssign)
description: "Returns page of user data objects that can be assigned to provided alarmId. Search is been executed by email, firstName and lastName fields. You can specify parameters to filter the results. The result is wrapped with PageData object that allows you to iterate over result set using pagination. See response schema for more details. \n\nAvailable for users with 'TENANT_ADMIN' or 'CUSTOMER_USER' authority."
operationId: getUsersForAssign
parameters:
- name: alarmId
in: path
description: A string value representing the alarm id. For example, '784f394c-42b6-435a-983c-b7beff2784f9'
required: true
schema:
type: string
- name: pageSize
in: query
description: Maximum amount of entities in a one page
required: true
schema:
type: integer
format: int32
- name: page
in: query
description: Sequence number of page starting from 0
required: true
schema:
type: integer
format: int32
- name: textSearch
in: query
description: The case insensitive 'substring' filter based on the user email.
required: false
schema:
type: string
- name: sortProperty
in: query
description: Property of entity to sort by
required: false
schema:
type: string
enum:
- createdTime
- firstName
- lastName
- email
- name: sortOrder
in: query
description: Sort order. ASC (ASCENDING) or DESC (DESCENDING)
required: false
schema:
type: string
enum:
- ASC
- DESC
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/PageDataUserEmailInfo'
/api/user/{userId}:
get:
tags:
- user-controller
summary: Get User (getUserById)
description: Fetch the User object based on the provided User Id. If the user has the authority of 'SYS_ADMIN', the server does not perform additional checks. If the user has the authority of 'TENANT_ADMIN', the server checks that the requested user is owned by the same tenant. If the user has the authority of 'CUSTOMER_USER', the server checks that the requested user is owned by the same customer.
operationId: getUserById
parameters:
- name: userId
in: path
description: A string value representing the user id. For example, '784f394c-42b6-435a-983c-b7beff2784f9'
required: true
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/User'
delete:
tags:
- user-controller
summary: Delete User (deleteUser)
description: "Deletes the User, it's credentials and all the relations (from and to the User). Referencing non-existing User Id will cause an error. \n\nAvailable for users with 'SYS_ADMIN' or 'TENANT_ADMIN' authority."
operationId: deleteUser
parameters:
- name: userId
in: path
description: A string value representing the user id. For example, '784f394c-42b6-435a-983c-b7beff2784f9'
required: true
schema:
type: string
responses:
'200':
description: OK
/api/user/{userId}/token:
get:
tags:
- user-controller
summary: Get User Token (getUserToken)
description: 'Returns the token of the User based on the provided User Id. If the user who performs the request has the authority of ''SYS_ADMIN'', it is possible to get the token of any tenant administrator. If the user who performs the request has the authority of ''TENANT_ADMIN'', it is possible to get the token of any customer user that belongs to the same tenant. '
operationId: getUserToken
parameters:
- name: userId
in: path
description: A string value representing the user id. For example, '784f394c-42b6-435a-983c-b7beff2784f9'
required: true
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/JwtPair'
/api/user/{userId}/activationLink:
get:
tags:
- user-controller
summary: Get Activation Link (getActivationLink)
description: "Get the activation link for the user. The base url for activation link is configurable in the general settings of system administrator. \n\nAvailable for users with 'SYS_ADMIN' or 'TENANT_ADMIN' authority."
operationId: getActivationLink
parameters:
- name: userId
in: path
description: A string value representing the user id. For example, '784f394c-42b6-435a-983c-b7beff2784f9'
required: true
schema:
type: string
responses:
'200':
description: OK
content:
text/plain:
schema:
type: string
/api/user/{userId}/activationLinkInfo:
get:
tags:
- user-controller
summary: Get Activation Link Info (getActivationLinkInfo)
description: "Get the activation link info for the user. The base url for activation link is configurable in the general settings of system administrator. \n\nAvailable for users with 'SYS_ADMIN' or 'TENANT_ADMIN' authority."
operationId: getActivationLinkInfo
parameters:
- name: userId
in: path
description: A string value representing the user id. For example, '784f394c-42b6-435a-983c-b7beff2784f9'
required: true
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/UserActivationLink'
/api/user/tokenAccessEnabled:
get:
tags:
- user-controller
summary: Check Token Access Enabled (isUserTokenAccessEnabled)
description: 'Checks that the system is configured to allow administrators to impersonate themself as other users. If the user who performs the request has the authority of ''SYS_ADMIN'', it is possible to login as any tenant administrator. If the user who performs the request has the authority of ''TENANT_ADMIN'', it is possible to login as any customer user. '
operationId: isUserTokenAccessEnabled
responses:
'200':
description: OK
content:
application/json:
schema:
type: boolean
/api/user/dashboards:
get:
tags:
- user-controller
summary: Get Information About Last Visited and Starred Dashboards (getLastVisitedDashboards)
description: 'Fetch the list of last visited and starred dashboards. Both lists are limited to 10 items.
Available for users with ''TENANT_ADMIN'' or ''CUSTOMER_USER'' authority.'
operationId: getUserDashboardsInfo
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/UserDashboardsInfo'
/api/user/dashboards/{dashboardId}/{action}:
get:
tags:
- user-controller
summary: Report Action of User Over the Dashboard (reportUserDashboardAction)
description: "Report action of User over the dashboard. \n\nAvailable for users with 'TENANT_ADMIN' or 'CUSTOMER_USER' authority."
operationId: reportUserDashboardAction
parameters:
- name: dashboardId
in: path
description: A string value representing the dashboard id. For example, '784f394c-42b6-435a-983c-b7beff2784f9'
required: true
schema:
type: string
- name: action
in: path
description: 'Dashboard action, one of: "visit", "star" or "unstar".'
required: true
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/UserDashboardsInfo'
/api/tenant/{tenantId}/users:
get:
tags:
- user-controller
summary: Get Tenant Users (getTenantAdmins)
description: "Returns a page of users owned by tenant. You can specify parameters to filter the results. The result is wrapped with PageData object that allows you to iterate over result set using pagination. See response schema for more details. \n\nAvailable for users with 'SYS_ADMIN' authority."
operationId: getTenantAdmins
parameters:
- name: tenantId
in: path
description: A string value representing the tenant id. For example, '784f394c-42b6-435a-983c-b7beff2784f9'
required: true
schema:
type: string
- name: pageSize
in: query
description: Maximum amount of entities in a one page
required: true
schema:
type: integer
format: int32
- name: page
in: query
description: Sequence number of page starting from 0
required: true
schema:
type: integer
format: int32
- name: textSearch
in: query
description: The case insensitive 'substring' filter based on the user email.
required: false
schema:
type: string
- name: sortProperty
in: query
description: Property of entity to sort by
required: false
schema:
type: string
enum:
- createdTime
- firstName
- lastName
- email
- name: sortOrder
in: query
description: Sort order. ASC (ASCENDING) or DESC (DESCENDING)
required: false
schema:
type: string
enum:
- ASC
- DESC
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/PageDataUser'
/api/customer/{customerId}/users:
get:
tags:
- user-controller
summary: Get Customer Users (getCustomerUsers)
description: "Returns a page of users owned by customer. You can specify parameters to filter the results. The result is wrapped with PageData object that allows you to iterate over result set using pagination. See response schema for more details. \n\nAvailable for users with 'TENANT_ADMIN' authority."
operationId: getCustomerUsers
parameters:
- name: customerId
in: path
description: A string value representing the customer id. For example, '784f394c-42b6-435a-983c-b7beff2784f9'
required: true
schema:
type: string
- name: pageSize
in: query
description: Maximum amount of entities in a one page
required: true
schema:
type: integer
format: int32
- name: page
in: query
description: Sequence number of page starting from 0
required: true
schema:
type: integer
format: int32
- name: textSearch
in: query
description: The case insensitive 'substring' filter based on the user email.
required: false
schema:
type: string
- name: sortProperty
in: query
description: Property of entity to sort by
required: false
schema:
type: string
enum:
- createdTime
- firstName
- lastName
- email
- name: sortOrder
in: query
description: Sort order. ASC (ASCENDING) or DESC (DESCENDING)
required: false
schema:
type: string
enum:
- ASC
- DESC
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/PageDataUser'
/api/user/settings/{type}/{paths}:
delete:
tags:
- user-controller
summary: Delete User Settings (deleteUserSettings)
description: "Delete user settings by specifying list of json element xpaths. \n Example: to delete B and C element in { \"A\": {\"B\": 5}, \"C\": 15} send A.B,C in jsonPaths request parameter"
operationId: deleteUserSettings
parameters:
- name: paths
in: path
description: paths
required: true
schema:
type: string
- name: type
in: path
description: 'Settings type, case insensitive, one of: "general", "quick_links", "doc_links" or "dashboards".'
required: true
schema:
type: string
responses:
'200':
description: OK
/api/user/settings/{paths}:
delete:
tags:
- user-controller
summary: Delete User Settings (deleteUserSettings)
description: "Delete user settings by specifying list of json element xpaths. \n Example: to delete B and C element in { \"A\": {\"B\": 5}, \"C\": 15} send A.B,C in jsonPaths request parameter"
operationId: deleteUserSettings_1
parameters:
- name: paths
in: path
description: paths
required: true
schema:
type: string
responses:
'200':
description: OK
components:
schemas:
UserDashboardsInfo:
type: object
properties:
last:
type: array
description: List of last visited dashboards.
items:
$ref: '#/components/schemas/LastVisitedDashboardInfo'
readOnly: true
starred:
type: array
description: List of starred dashboards.
items:
$ref: '#/components/schemas/StarredDashboardInfo'
readOnly: true
JsonNode:
description: A value representing the any type (object or primitive)
examples:
- {}
MobileSessionInfo:
type: object
properties:
fcmTokenTimestamp:
type: integer
format: int64
UserId:
type: object
properties:
id:
type: string
format: uuid
description: ID of the entity, time-based UUID v1
example: 784f394c-42b6-435a-983c-b7beff2784f9
entityType:
type: string
description: string
enum:
- USER
example: USER
required:
- entityType
- id
UserActivationLink:
type: object
properties:
value:
type: string
ttlMs:
type: integer
format: int64
PageDataUserEmailInfo:
type: object
properties:
data:
type: array
description: Array of the entities
items:
$ref: '#/components/schemas/UserEmailInfo'
readOnly: true
totalPages:
type: integer
format: int32
description: Total number of available pages. Calculated based on the 'pageSize' request parameter and total number of entities that match search criteria
readOnly: true
totalElements:
type: integer
format: int64
description: Total number of elements in all available pages
readOnly: true
hasNext:
type: boolean
description: '''false'' value indicates the end of the result set'
readOnly: true
LastVisitedDashboardInfo:
type: object
properties:
id:
type: string
format: uuid
description: JSON object with Dashboard id.
readOnly: true
title:
type: string
description: Title of the dashboard.
starred:
type: boolean
description: Starred flag
lastVisited:
type: integer
format: int64
description: Last visit timestamp
StarredDashboardInfo:
type: object
properties:
id:
type: string
format: uuid
description: JSON object with Dashboard id.
readOnly: true
title:
type: string
description: Title of the dashboard.
starredAt:
type: integer
format: int64
description: Starred timestamp
User:
type: object
description: A JSON value representing the User.
properties:
id:
$ref: '#/components/schemas/UserId'
description: JSON object with the User Id. Specify this field to update the device. Referencing non-existing User Id will cause error. Omit this field to create new customer.
createdTime:
type: integer
format: int64
description: Timestamp of the user creation, in milliseconds
example: 1609459200000
readOnly: true
tenantId:
$ref: '#/components/schemas/TenantId'
description: JSON object with the Tenant Id.
readOnly: true
customerId:
$ref: '#/components/schemas/CustomerId'
description: JSON object with the Customer Id.
readOnly: true
email:
type: string
description: Email of the user
example: user@example.com
authority:
type: string
description: Authority
enum:
- SYS_ADMIN
- TENANT_ADMIN
- CUSTOMER_USER
- REFRESH_TOKEN
- PRE_VERIFICATION_TOKEN
- MFA_CONFIGURATION_TOKEN
example: SYS_ADMIN, TENANT_ADMIN or CUSTOMER_USER
firstName:
type: string
description: First name of the user
example: John
lastName:
type: string
description: Last name of the user
example: Doe
phone:
type: string
description: Phone number of the user
example: 38012345123
version:
type: integer
format: int64
name:
type: string
description: Duplicates the email of the user, readonly
example: user@example.com
readOnly: true
additionalInfo:
$ref: '#/components/schemas/JsonNode'
description: Additional parameters of the user
required:
- authority
- email
TenantId:
type: object
properties:
id:
type: string
format: uuid
description: ID of the entity, time-based UUID v1
example: 784f394c-42b6-435a-983c-b7beff2784f9
entityType:
type: string
description: string
enum:
- TENANT
example: TENANT
required:
- entityType
- id
CustomerId:
type: object
properties:
id:
type: string
format: uuid
description: ID of the entity, time-based UUID v1
example: 784f394c-42b6-435a-983c-b7beff2784f9
entityType:
type: string
description: string
enum:
- CUSTOMER
example: CUSTOMER
required:
- entityType
- id
UserEmailInfo:
type: object
properties:
id:
$ref: '#/components/schemas/UserId'
description: User id
email:
type: string
description: User email
example: john@gmail.com
firstName:
type: string
description: User first name
example: John
lastName:
type: string
description: User last name
example: Brown
JwtPair:
type: object
description: JWT Pair
properties:
token:
type: string
description: The JWT Access Token. Used to perform API calls.
example: AAB254FF67D..
refreshToken:
type: string
description: The JWT Refresh Token. Used to get new JWT Access Token if old one has expired.
example: AAB254FF67D..
scope:
type: string
enum:
- SYS_ADMIN
- TENANT_ADMIN
- CUSTOMER_USER
- REFRESH_TOKEN
- PRE_VERIFICATION_TOKEN
- MFA_CONFIGURATION_TOKEN
PageDataUser:
type: object
properties:
data:
type: array
description: Array of the entities
ite
# --- truncated at 32 KB (33 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/thingsboard/refs/heads/main/openapi/thingsboard-user-controller-api-openapi.yml