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 items: $ref: '#/components/schemas/User' 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 securitySchemes: HTTP login form: type: http description: Enter Username / Password scheme: loginPassword bearerFormat: /api/auth/login|X-Authorization API key form: type: apiKey description: 'Enter the API key value with ''ApiKey'' prefix in format: **ApiKey ** Example: **ApiKey tb_5te51SkLRYpjGrujUGwqkjFvooWBlQpVe2An2Dr3w13wjfxDW**
**NOTE**: Use only ONE authentication method at a time. If both are authorized, JWT auth takes the priority.
' name: X-Authorization in: header