# ThingsBoard ThingsBoard Authentication API
# Source: https://demo.thingsboard.io/v3/api-docs (Apache 2.0)
openapi: 3.1.0
info:
title: ThingsBoard Authentication API
description: "ThingsBoard Authentication API \u2014 subset of the ThingsBoard REST API (open-source IoT platform). Covers: Login, Auth, Sign Up, Api Key, Two Factor Auth, Two Factor Auth Config, O Auth\
\ 2, O Auth 2 Config Template, Domain."
version: 4.3.0.3DEMO
contact:
name: ThingsBoard team
url: https://thingsboard.io
email: [email protected]
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: login-endpoint
description: Login
- name: auth-controller
description: Auth
- name: sign-up-controller
description: Sign Up
- name: api-key-controller
description: Api Key
- name: two-factor-auth-controller
description: Two Factor Auth
- name: two-factor-auth-config-controller
description: Two Factor Auth Config
- name: o-auth-2-controller
description: O Auth 2
- name: o-auth-2-config-template-controller
description: O Auth 2 Config Template
- name: domain-controller
description: Domain
paths:
/api/auth/login:
post:
tags:
- login-endpoint
summary: Login Method to Get User JWT Token Data
description: 'Login method used to authenticate user and get JWT token data.
Value of the response **token** field can be used as **X-Authorization** header value:
`X-Authorization: Bearer $JWT_TOKEN_VALUE`.'
requestBody:
description: Login request
content:
application/json:
schema:
$ref: '#/components/schemas/LoginRequest'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/LoginResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ThingsboardErrorResponse'
examples:
account-disabled:
summary: Disabled account
value:
status: 401
message: User account is not active
errorCode: 10
timestamp: 1770209248175
bad-credentials:
summary: Bad credentials
value:
status: 401
message: Invalid username or password
errorCode: 10
timestamp: 1770209248175
account-locked:
summary: Locked account
value:
status: 401
message: User account is locked due to security policy
errorCode: 10
timestamp: 1770209248175
token-expired:
summary: JWT token expired
value:
status: 401
message: Token has expired
errorCode: 11
timestamp: 1770209248175
authentication-failed:
summary: General authentication error
value:
status: 401
message: Authentication failed
errorCode: 10
timestamp: 1770209248175
'401 ':
description: Unauthorized (**Expired credentials**)
content:
application/json:
schema:
$ref: '#/components/schemas/ThingsboardCredentialsExpiredResponse'
examples:
credentials-expired:
summary: Expired credentials
value:
status: 401
message: User password expired!
errorCode: 15
timestamp: 1770209248182
resetToken: 59B5IkNuDrCyn98QB8LJ1sWFzwA03A
/api/auth/token:
post:
tags:
- login-endpoint
summary: Refresh User JWT Token Data
description: 'Method to refresh JWT token. Provide a valid refresh token to get a new JWT token.
The response contains a new token that can be used for authorization.
`X-Authorization: Bearer $JWT_TOKEN_VALUE`'
requestBody:
description: Refresh token request
content:
application/json:
schema:
properties:
refreshToken: {}
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/LoginResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ThingsboardErrorResponse'
examples:
account-disabled:
summary: Disabled account
value:
status: 401
message: User account is not active
errorCode: 10
timestamp: 1770209248175
bad-credentials:
summary: Bad credentials
value:
status: 401
message: Invalid username or password
errorCode: 10
timestamp: 1770209248175
account-locked:
summary: Locked account
value:
status: 401
message: User account is locked due to security policy
errorCode: 10
timestamp: 1770209248175
token-expired:
summary: JWT token expired
value:
status: 401
message: Token has expired
errorCode: 11
timestamp: 1770209248175
authentication-failed:
summary: General authentication error
value:
status: 401
message: Authentication failed
errorCode: 10
timestamp: 1770209248175
'401 ':
description: Unauthorized (**Expired credentials**)
content:
application/json:
schema:
$ref: '#/components/schemas/ThingsboardCredentialsExpiredResponse'
examples:
credentials-expired:
summary: Expired credentials
value:
status: 401
message: User password expired!
errorCode: 15
timestamp: 1770209248182
resetToken: 59B5IkNuDrCyn98QB8LJ1sWFzwA03A
/api/domain/{id}/oauth2Clients:
put:
tags:
- domain-controller
summary: Update Oauth2 Clients (updateOauth2Clients)
description: 'Update oauth2 clients for the specified domain. '
operationId: updateOauth2Clients_1
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
requestBody:
content:
application/json:
schema:
type: array
items:
type: string
format: uuid
required: true
responses:
'200':
description: OK
/api/apiKey/{id}/enabled/{enabledValue}:
put:
tags:
- api-key-controller
summary: Enable or Disable API Key (enableApiKey)
description: "Updates api key with enabled = true/false. \n\nAvailable for any authorized user. "
operationId: enableApiKey
parameters:
- name: id
in: path
description: Unique identifier of the API key to enable/disable
required: true
schema:
type: string
format: uuid
- name: enabledValue
in: path
description: Enabled or disabled api key
required: true
schema:
type: boolean
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ApiKeyInfo'
/api/apiKey/{id}/description:
put:
tags:
- api-key-controller
summary: Update API Key Description
description: 'Updates the description of the existing API key by apiKeyId. Only the description can be updated. Referencing a non-existing ApiKey Id will cause a ''Not Found'' error.
Available for any authorized user. '
operationId: updateApiKeyDescription
parameters:
- name: id
in: path
description: A string value representing the api key id. For example, '784f394c-42b6-435a-983c-b7beff2784f9'
required: true
schema:
type: string
format: uuid
requestBody:
content:
application/json:
schema:
type: string
description: New description for the API key
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ApiKeyInfo'
/api/2fa/account/config:
put:
tags:
- two-factor-auth-config-controller
summary: Update 2FA Account Config (updateTwoFaAccountConfig)
description: "Update config for a given provider type. \nUpdate request example:\n```\n{\n \"useByDefault\": true\n}\n```\nReturns whole account's 2FA settings object.\n\n\nAvailable for any authorized\
\ user. "
operationId: updateTwoFaAccountConfig
parameters:
- name: providerType
in: query
required: true
schema:
type: string
enum:
- TOTP
- SMS
- EMAIL
- BACKUP_CODE
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/TwoFaAccountConfigUpdateRequest'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AccountTwoFaSettings'
post:
tags:
- two-factor-auth-config-controller
summary: Verify and Save 2FA Account Config (verifyAndSaveTwoFaAccountConfig)
description: "Checks the verification code for submitted config, and if it is correct, saves the provided account config. \n\nReturns whole account's 2FA settings object.\nWill throw an error (Bad\
\ Request) if the provider is not configured for usage. \n\nAvailable for any authorized user. "
operationId: verifyAndSaveTwoFaAccountConfig
parameters:
- name: verificationCode
in: query
required: false
schema:
type: string
requestBody:
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/BackupCodeTwoFaAccountConfig'
- $ref: '#/components/schemas/EmailTwoFaAccountConfig'
- $ref: '#/components/schemas/SmsTwoFaAccountConfig'
- $ref: '#/components/schemas/TotpTwoFaAccountConfig'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AccountTwoFaSettings'
delete:
tags:
- two-factor-auth-config-controller
summary: Delete 2FA Account Config (deleteTwoFaAccountConfig)
description: "Delete 2FA config for a given 2FA provider type. \nReturns whole account's 2FA settings object.\n\n\nAvailable for any authorized user. "
operationId: deleteTwoFaAccountConfig
parameters:
- name: providerType
in: query
required: true
schema:
type: string
enum:
- TOTP
- SMS
- EMAIL
- BACKUP_CODE
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AccountTwoFaSettings'
/api/signup/acceptPrivacyPolicy:
post:
tags:
- sign-up-controller
operationId: acceptPrivacyPolicy
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/JwtPair'
/api/oauth2/config/template:
get:
tags:
- o-auth-2-config-template-controller
summary: Get the List of All OAuth2 Client Registration Templates (getClientRegistrationTemplates) Available for Users with 'SYS_ADMIN' or 'TENANT_ADMIN' Authority.
description: Client registration template is OAuth2 provider configuration template with default settings for registering new OAuth2 clients
operationId: getClientRegistrationTemplates
responses:
'200':
description: OK
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/OAuth2ClientRegistrationTemplate'
post:
tags:
- o-auth-2-config-template-controller
summary: Create or Update OAuth2 Client Registration Template (saveClientRegistrationTemplate) Available for Users with 'SYS_ADMIN' Authority.
description: Client registration template is OAuth2 provider configuration template with default settings for registering new OAuth2 clients
operationId: saveClientRegistrationTemplate
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/OAuth2ClientRegistrationTemplate'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/OAuth2ClientRegistrationTemplate'
/api/oauth2/client:
post:
tags:
- o-auth-2-controller
summary: Save OAuth2 Client (saveOAuth2Client)
description: '
Available for users with ''SYS_ADMIN'' or ''TENANT_ADMIN'' authority.'
operationId: saveOAuth2Client
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/OAuth2Client'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/OAuth2Client'
/api/noauth/signup:
post:
tags:
- sign-up-controller
operationId: signUp
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/SignUpRequest'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
type: string
enum:
- SUCCESS
- INACTIVE_USER_EXISTS
/api/noauth/resetPassword:
get:
tags:
- auth-controller
summary: Check Password Reset Token (checkResetToken)
description: Checks the password reset token and forwards user to 'Reset Password' page. If token is valid, returns '303 See Other' (redirect) response code with the correct address of 'Reset Password'
page and same 'resetToken' specified in the URL parameters. If token is not valid, returns '409 Conflict'. If token is expired, redirects to error page.
operationId: checkResetToken
parameters:
- name: resetToken
in: query
description: The reset token string.
required: true
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
post:
tags:
- auth-controller
summary: Reset Password (resetPassword)
description: Checks the password reset token and updates the password. If token is not valid, returns '400 Bad Request'.
operationId: resetPassword
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ResetPasswordRequest'
required: true
responses:
'200':
description: OK
/api/noauth/resetPasswordByEmail:
post:
tags:
- auth-controller
summary: Request Reset Password Email (requestResetPasswordByEmail)
description: Request to send the reset password email if the user with specified email address is present in the database. Always return '200 OK' status for security purposes.
operationId: requestResetPasswordByEmail
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ResetPasswordEmailRequest'
required: true
responses:
'200':
description: OK
/api/noauth/resendEmailActivation:
post:
tags:
- sign-up-controller
operationId: resendEmailActivation
parameters:
- name: email
in: query
required: true
schema:
type: string
- name: pkgName
in: query
required: false
schema:
type: string
responses:
'200':
description: OK
/api/noauth/oauth2Clients:
post:
tags:
- o-auth-2-controller
summary: Get OAuth2 Clients (getOAuth2Clients)
description: Get the list of OAuth2 clients to log in with, available for such domain scheme (HTTP or HTTPS) (if x-forwarded-proto request header is present - the scheme is known from it) and domain
name and port (port may be known from x-forwarded-port header)
operationId: getOAuth2Clients
parameters:
- name: pkgName
in: query
description: Mobile application package name, to find OAuth2 clients where there is configured mobile application with such package name
required: false
schema:
type: string
- name: platform
in: query
description: Platform type to search OAuth2 clients for which the usage with this platform type is allowed in the settings. If platform type is not one of allowable values - it will just be ignored
required: false
schema:
type: string
enum:
- WEB
- ANDROID
- IOS
responses:
'200':
description: OK
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/OAuth2ClientLoginInfo'
/api/noauth/activate:
get:
tags:
- auth-controller
summary: Check Activate User Token (checkActivateToken)
description: Checks the activation token and forwards user to 'Create Password' page. If token is valid, returns '303 See Other' (redirect) response code with the correct address of 'Create Password'
page and same 'activateToken' specified in the URL parameters. If token is not valid, returns '409 Conflict'. If token is expired, redirects to error page.
operationId: checkActivateToken
parameters:
- name: activateToken
in: query
description: The activate token string.
required: true
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
post:
tags:
- auth-controller
summary: Activate User
description: Checks the activation token and updates corresponding user password in the database. Now the user may start using his password to login. The response already contains the [JWT](https://jwt.io)
activation and refresh tokens, to simplify the user activation flow and avoid asking user to input password again after activation. If token is valid, returns the object that contains [JWT](https://jwt.io/)
access and refresh tokens. If token is not valid, returns '400 Bad Request'.
operationId: activateUser
parameters:
- name: sendActivationMail
in: query
required: false
schema:
type: boolean
default: true
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ActivateUserRequest'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/JwtPair'
/api/noauth/activateByEmailCode:
post:
tags:
- sign-up-controller
operationId: activateUserByEmailCode
parameters:
- name: emailCode
in: query
required: true
schema:
type: string
- name: pkgName
in: query
required: false
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/JwtPair'
/api/domain:
post:
tags:
- domain-controller
summary: Save or Update Domain (saveDomain)
description: 'Create or update the Domain. When creating domain, platform generates Domain Id as [time-based UUID](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_1_(date-time_and_MAC_address)).
The newly created Domain Id will be present in the response. Specify existing Domain Id to update the domain. Referencing non-existing Domain Id will cause ''Not Found'' error.
Domain name is unique for entire platform setup.
Available for users with ''SYS_ADMIN'' authority.'
operationId: saveDomain
parameters:
- name: oauth2ClientIds
in: query
description: A list of oauth2 client registration ids, separated by comma ','
required: false
schema:
type: array
items:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Domain'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Domain'
/api/auth/logout:
post:
tags:
- auth-controller
summary: Logout (logout)
description: 'Special API call to record the ''logout'' of the user to the Audit Logs. Since platform uses [JWT](https://jwt.io/), the actual logout is the procedure of clearing the [JWT](https://jwt.io/)
token on the client side. '
operationId: logout
responses:
'200':
description: OK
/api/auth/changePassword:
post:
tags:
- auth-controller
summary: Change Password for Current User (changePassword)
description: Change the password for the User which credentials are used to perform this REST API call. Be aware that previously generated [JWT](https://jwt.io/) tokens will be still valid until they
expire.
operationId: changePassword
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ChangePasswordRequest'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/JwtPair'
/api/auth/2fa/verification/send:
post:
tags:
- two-factor-auth-controller
summary: Request 2FA Verification Code (requestTwoFaVerificationCode)
description: 'Request 2FA verification code.
To make a request to this endpoint, you need an access token with the scope of PRE_VERIFICATION_TOKEN, which is issued on username/password auth if 2FA is enabled.
The API method is rate limited (using rate limit config from TwoFactorAuthSettings). Will return a Bad Request error if provider is not configured for usage, and Too Many Requests error if rate
limits are exceeded.'
operationId: requestTwoFaVerificationCode
parameters:
- name: providerType
in: query
required: true
schema:
type: string
enum:
- TOTP
- SMS
- EMAIL
- BACKUP_CODE
responses:
'200':
description: OK
/api/auth/2fa/verification/check:
post:
tags:
- two-factor-auth-controller
summary: Check 2FA Verification Code (checkTwoFaVerificationCode)
description: 'Checks 2FA verification code, and if it is correct the method returns a regular access and refresh token pair.
The API method is rate limited (using rate limit config from TwoFactorAuthSettings), and also will block a user after X unsuccessful verification attempts if such behavior is configured (in TwoFactorAuthSettings).
Will return a Bad Request error if provider is not configured for usage, and Too Many Requests error if rate limits are exceeded.'
operationId: checkTwoFaVerificationCode
parameters:
- name: providerType
in: query
required: true
schema:
type: string
enum:
- TOTP
- SMS
- EMAIL
- BACKUP_CODE
- name: verificationCode
in: query
required: true
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/JwtPair'
/api/auth/2fa/login:
post:
tags:
- two-factor-auth-controller
summary: Get Regular Token Pair After Successfully Configuring 2FA
description: Checks 2FA is configured, returning token pair on success.
operationId: authenticateByTwoFaConfigurationToken
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/JwtPair'
/api/apiKey:
post:
tags:
- api-key-controller
summary: Save API Key for User (saveApiKey)
description: 'Creates an API key for the given user and returns the token ONCE as ''ApiKey <value>''.
Available for any authorized user. '
operationId: saveApiKey
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ApiKeyInfo'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ApiKey'
/api/2fa/settings:
get:
tags:
- two-factor-auth-config-controller
summary: Get Platform 2FA Settings (getPlatformTwoFaSettings)
description: 'Get platform settings for 2FA. The settings are described for savePlatformTwoFaSettings API method. If 2FA is not configured, then an empty response will be returned.
Available for users with ''SYS_ADMIN'' or ''TENANT_ADMIN'' authority.'
operationId: getPlatformTwoFaSettings
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/PlatformTwoFaSettings'
post:
tags:
- two-factor-auth-config-controller
summary: Save Platform 2FA Settings (savePlatformTwoFaSettings)
description: "Save 2FA settings for platform. The settings have following properties:\n- `providers` - the list of 2FA providers' configs. Users will only be allowed to use 2FA providers from this\
\ list. \n\n- `minVerificationCodeSendPeriod` - minimal period in seconds to wait after verification code send request to send next request. \n- `verificationCodeCheckRateLimit` - rate limit configuration\
\ for verification code checking.\nThe format is standard: 'amountOfRequests:periodInSeconds'. The value of '1:60' would limit verification code checking requests to one per minute.\n- `maxVerificationFailuresBeforeUserLockout`\
\ - maximum number of verification failures before a user gets disabled.\n- `totalAllowedTimeForVerification` - total amount of time in seconds allotted for verification. Basically, this property\
\ sets a lifetime for pre-verification token. If not set, default value of 30 minutes is used.\n\n\nTOTP 2FA provider config has following settings:\n- `issuerName` - issuer name that will be displayed\
\ in an authenticator app near a username. Must not be blank.\n\nFor SMS 2FA provider:\n- `smsVerificationMessageTemplate` - verification message template. Available template variables are ${code}\
\ and ${userEmail}. It must not be blank and must contain verification code variable.\n- `verificationCodeLifetime` - verification code lifetime in seconds. Required to be positive.\n\nFor EMAIL\
\ provider type:\n- `verificationCodeLifetime` - the same as for SMS.\n\nExample of the settings:\n```\n{\n \"providers\": [\n {\n \"providerType\": \"TOTP\",\n \"issuerName\": \"\
TB\"\n },\n {\n \"providerType\": \"EMAIL\",\n \"verificationCodeLifetime\": 60\n },\n {\n \"providerType\": \"SMS\",\n \"verificationCodeLifetime\": 60,\n \"\
smsVerificationMessageTemplate\": \"Here is your verification code: ${code}\"\n }\n ],\n \"minVerificationCodeSendPeriod\": 60,\n \"verificationCodeCheckRateLimit\": \"3:900\",\n \"maxVerificationFailuresBeforeUserLockout\"\
: 10,\n \"totalAllowedTimeForVerification\": 600\n}\n```\n\nAvailable for users with 'SYS_ADMIN' or 'TENANT_ADMIN' authority."
operationId: savePlatformTwoFaSettings
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PlatformTwoFaSettings'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/PlatformTwoFaSettings'
/api/2fa/account/config/submit:
post:
tags:
- two-factor-auth-config-controller
summary: Submit 2FA Account Config (submitTwoFaAccountConfig)
description: "Submit 2FA account config to prepare for a future verification. Basically, this method will send a verification code for a given account config, if this has sense for a chosen 2FA provider.\
\ This code is needed to then verify and save the account config.\n\nExample of EMAIL 2FA account config:\n```\n{\n \"providerType\": \"EMAIL\",\n \"useByDefault\": true,\n \"email\": \"[email protected]\"\
\n}\n```\n\nExample of SMS 2FA account config:\n```\n{\n \"providerType\": \"SMS\",\n \"useByDefault\": false,\n \"phoneNumber\": \"+38012312321\"\n}\n```\n\nFor TOTP this method does nothing.\n\
\nWill throw an error (Bad Request) if submitted account config is not valid, or if the provider is not configured for usage. \n\nAvailable for any authorized user. "
operationId: submitTwoFaAccountConfig
requestBody:
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/BackupCodeTwoFaAccountConfig'
- $ref: '#/components/schemas/EmailTwoFaAccountConfig'
- $ref: '#/components/schemas/SmsTwoFaAccountConfig'
- $ref: '#/components/schemas/TotpTwoFaAccountConfig'
required: true
responses:
'200':
description: OK
/api/2fa/account/config/generate:
post:
tags:
- two-factor-auth-config-controller
summary: Generate 2FA Account Config (generateTwoFaAccountConfig)
description: "Generate new 2FA account config template for specified provider type. \n\nFor TOTP, this w
# --- truncated at 32 KB (84 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/thingsboard/refs/heads/main/openapi/thingsboard-auth-openapi.yml