openapi: 3.1.0 info: title: ThingsBoard Admin admin-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: admin-controller description: Admin paths: /api/admin/settings: post: tags: - admin-controller summary: Creates or Updates the Administration Settings (saveAdminSettings) description: 'Creates or Updates the Administration Settings. Platform generates random Administration Settings Id during settings creation. The Administration Settings Id will be present in the response. Specify the Administration Settings Id when you would like to update the Administration Settings. Referencing non-existing Administration Settings Id will cause an error. Available for users with ''SYS_ADMIN'' authority.' operationId: saveAdminSettings requestBody: content: application/json: schema: $ref: '#/components/schemas/AdminSettings' required: true responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/AdminSettings' /api/admin/settings/testSms: post: tags: - admin-controller summary: Send Test Sms (sendTestSms) description: "Attempts to send test sms to the System Administrator User using SMS Settings and phone number provided as a parameters of the request. \n\nAvailable for users with 'SYS_ADMIN' authority." operationId: sendTestSms requestBody: content: application/json: schema: $ref: '#/components/schemas/TestSmsRequest' required: true responses: '200': description: OK /api/admin/settings/testMail: post: tags: - admin-controller summary: Send Test Email (sendTestMail) description: "Attempts to send test email to the System Administrator User using Mail Settings provided as a parameter. You may change the 'To' email in the user profile of the System Administrator. \n\nAvailable for users with 'SYS_ADMIN' authority." operationId: sendTestMail requestBody: content: application/json: schema: $ref: '#/components/schemas/AdminSettings' required: true responses: '200': description: OK /api/admin/securitySettings: get: tags: - admin-controller summary: Get the Security Settings Object (getSecuritySettings) description: 'Get the Security Settings object that contains password policy, etc. Available for users with ''SYS_ADMIN'' authority.' operationId: getSecuritySettings responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/SecuritySettings' post: tags: - admin-controller summary: Update Security Settings (saveSecuritySettings) description: 'Updates the Security Settings object that contains password policy, etc. Available for users with ''SYS_ADMIN'' authority.' operationId: saveSecuritySettings requestBody: content: application/json: schema: $ref: '#/components/schemas/SecuritySettings' required: true responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/SecuritySettings' /api/admin/repositorySettings: get: tags: - admin-controller summary: Get Repository Settings (getRepositorySettings) description: "Get the repository settings object. \n\nAvailable for users with 'TENANT_ADMIN' authority." operationId: getRepositorySettings responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/RepositorySettings' post: tags: - admin-controller summary: Creates or Updates the Repository Settings (saveRepositorySettings) description: "Creates or Updates the repository settings object. \n\nAvailable for users with 'TENANT_ADMIN' authority." operationId: saveRepositorySettings requestBody: content: application/json: schema: $ref: '#/components/schemas/RepositorySettings' required: true responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/RepositorySettings' delete: tags: - admin-controller summary: Delete Repository Settings (deleteRepositorySettings) description: 'Deletes the repository settings. Available for users with ''TENANT_ADMIN'' authority.' operationId: deleteRepositorySettings responses: '200': description: OK /api/admin/repositorySettings/checkAccess: post: tags: - admin-controller summary: Check Repository Access (checkRepositoryAccess) description: "Attempts to check repository access. \n\nAvailable for users with 'TENANT_ADMIN' authority." operationId: checkRepositoryAccess requestBody: content: application/json: schema: $ref: '#/components/schemas/RepositorySettings' required: true responses: '200': description: OK /api/admin/jwtSettings: get: tags: - admin-controller summary: Get the JWT Settings Object (getJwtSettings) description: "Get the JWT Settings object that contains JWT token policy, etc. \n\nAvailable for users with 'SYS_ADMIN' authority." operationId: getJwtSettings responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/JwtSettings' post: tags: - admin-controller summary: Update JWT Settings (saveJwtSettings) description: 'Updates the JWT Settings object that contains JWT token policy, etc. The tokenSigningKey field is a Base64 encoded string. Available for users with ''SYS_ADMIN'' authority.' operationId: saveJwtSettings requestBody: content: application/json: schema: $ref: '#/components/schemas/JwtSettings' required: true responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/JwtPair' /api/admin/autoCommitSettings: get: tags: - admin-controller summary: Get Auto Commit Settings (getAutoCommitSettings) description: "Get the auto commit settings object. \n\nAvailable for users with 'TENANT_ADMIN' authority." operationId: getAutoCommitSettings responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/AutoCommitSettings' post: tags: - admin-controller summary: Creates or Updates the Auto Commit Settings (saveAutoCommitSettings) description: "Creates or Updates the auto commit settings object. \n\nAvailable for users with 'TENANT_ADMIN' authority." operationId: saveAutoCommitSettings requestBody: content: application/json: schema: $ref: '#/components/schemas/AutoCommitSettings' required: true responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/AutoCommitSettings' delete: tags: - admin-controller summary: Delete Auto Commit Settings (deleteAutoCommitSettings) description: 'Deletes the auto commit settings. Available for users with ''TENANT_ADMIN'' authority.' operationId: deleteAutoCommitSettings responses: '200': description: OK /api/admin/updates: get: tags: - admin-controller summary: Check for New Platform Releases (checkUpdates) description: "Check notifications about new platform releases. \n\nAvailable for users with 'SYS_ADMIN' authority." operationId: checkUpdates responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/UpdateMessage' /api/admin/systemInfo: get: tags: - admin-controller summary: Get System Info (getSystemInfo) description: "Get main information about system. \n\nAvailable for users with 'SYS_ADMIN' authority." operationId: getSystemInfo responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/SystemInfo' /api/admin/settings/{key}: get: tags: - admin-controller summary: Get the Administration Settings Object Using Key (getAdminSettings) description: 'Get the Administration Settings object using specified string key. Referencing non-existing key will cause an error. Available for users with ''SYS_ADMIN'' authority.' operationId: getAdminSettings parameters: - name: key in: path description: A string value of the key (e.g. 'general' or 'mail'). required: true schema: type: string responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/AdminSettings' /api/admin/repositorySettings/info: get: tags: - admin-controller operationId: getRepositorySettingsInfo responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/RepositorySettingsInfo' /api/admin/repositorySettings/exists: get: tags: - admin-controller summary: Check Repository Settings Exists (repositorySettingsExists) description: "Check whether the repository settings exists. \n\nAvailable for users with 'TENANT_ADMIN' authority." operationId: repositorySettingsExists responses: '200': description: OK content: application/json: schema: type: boolean /api/admin/mail/oauth2/loginProcessingUrl: get: tags: - admin-controller summary: Get OAuth2 Log in Processing URL (getMailProcessingUrl) description: "Returns the URL enclosed in double quotes. After successful authentication with OAuth2 provider and user consent for requested scope, it makes a redirect to this path so that the platform can do further log in processing and generating access tokens. \n\nAvailable for users with 'SYS_ADMIN' authority." operationId: getMailProcessingUrl responses: '200': description: OK content: application/json: schema: type: string /api/admin/mail/oauth2/code: get: tags: - admin-controller operationId: codeProcessingUrl parameters: - name: code in: query required: true schema: type: string - name: state in: query required: true schema: type: string responses: '200': description: OK /api/admin/mail/oauth2/authorize: get: tags: - admin-controller summary: Redirect User to Mail Provider Login Page. description: After user logged in and provided accessprovider sends authorization code to specified redirect uri.) operationId: getAuthorizationUrl responses: '200': description: OK content: application/text: schema: type: string /api/admin/featuresInfo: get: tags: - admin-controller summary: Get Features Info (getFeaturesInfo) description: "Get information about enabled/disabled features. \n\nAvailable for users with 'SYS_ADMIN' authority." operationId: getFeaturesInfo responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/FeaturesInfo' /api/admin/autoCommitSettings/exists: get: tags: - admin-controller summary: Check Auto Commit Settings Exists (autoCommitSettingsExists) description: "Check whether the auto commit settings exists. \n\nAvailable for users with 'TENANT_ADMIN' authority." operationId: autoCommitSettingsExists responses: '200': description: OK content: application/json: schema: type: boolean components: schemas: TwilioSmsProviderConfiguration: allOf: - $ref: '#/components/schemas/SmsProviderConfiguration' - type: object properties: accountSid: type: string description: Twilio account Sid. accountToken: type: string description: Twilio account Token. numberFrom: type: string description: The number/id of a sender. SmppSmsProviderConfiguration: allOf: - $ref: '#/components/schemas/SmsProviderConfiguration' - type: object properties: protocolVersion: type: string description: SMPP version enum: - 3.3, 3.4 host: type: string description: SMPP host port: type: integer format: int32 description: SMPP port systemId: type: string description: System ID password: type: string description: Password systemType: type: string description: System type bindType: type: string description: TX - Transmitter, RX - Receiver, TRX - Transciever. By default TX is used enum: - TX - RX - TRX serviceType: type: string description: Service type sourceAddress: type: string description: Source address sourceTon: type: string format: byte description: 'Source TON (Type of Number). Needed is source address is set. 5 by default. 0 - Unknown 1 - International 2 - National 3 - Network Specific 4 - Subscriber Number 5 - Alphanumeric 6 - Abbreviated' sourceNpi: type: string format: byte description: 'Source NPI (Numbering Plan Identification). Needed is source address is set. 0 by default. 0 - Unknown 1 - ISDN/telephone numbering plan (E163/E164) 3 - Data numbering plan (X.121) 4 - Telex numbering plan (F.69) 6 - Land Mobile (E.212) =6 8 - National numbering plan 9 - Private numbering plan 10 - ERMES numbering plan (ETSI DE/PS 3 01-3) 13 - Internet (IP) 18 - WAP Client Id (to be defined by WAP Forum)' destinationTon: type: string format: byte description: 'Destination TON (Type of Number). 5 by default. 0 - Unknown 1 - International 2 - National 3 - Network Specific 4 - Subscriber Number 5 - Alphanumeric 6 - Abbreviated' destinationNpi: type: string format: byte description: 'Destination NPI (Numbering Plan Identification). 0 by default. 0 - Unknown 1 - ISDN/telephone numbering plan (E163/E164) 3 - Data numbering plan (X.121) 4 - Telex numbering plan (F.69) 6 - Land Mobile (E.212) =6 8 - National numbering plan 9 - Private numbering plan 10 - ERMES numbering plan (ETSI DE/PS 3 01-3) 13 - Internet (IP) 18 - WAP Client Id (to be defined by WAP Forum)' addressRange: type: string description: Address range codingScheme: type: string format: byte description: '0 - SMSC Default Alphabet (ASCII for short and long code and to GSM for toll-free, used as default) 1 - IA5 (ASCII for short and long code, Latin 9 for toll-free (ISO-8859-9)) 2 - Octet Unspecified (8-bit binary) 3 - Latin 1 (ISO-8859-1) 4 - Octet Unspecified (8-bit binary) 5 - JIS (X 0208-1990) 6 - Cyrillic (ISO-8859-5) 7 - Latin/Hebrew (ISO-8859-8) 8 - UCS2/UTF-16 (ISO/IEC-10646) 9 - Pictogram Encoding 10 - Music Codes (ISO-2022-JP) 13 - Extended Kanji JIS (X 0212-1990) 14 - Korean Graphic Character Set (KS C 5601/KS X 1001)' enum: - 0-10 - 13-14 required: - host - password - port - protocolVersion - systemId RepositorySettingsInfo: type: object properties: configured: type: boolean readOnly: type: boolean FeaturesInfo: type: object properties: smsEnabled: type: boolean oauthEnabled: type: boolean twoFaEnabled: type: boolean emailEnabled: type: boolean notificationEnabled: type: boolean JwtSettings: type: object description: A JSON value representing the JWT Settings. properties: tokenExpirationTime: type: integer format: int32 description: The JWT will expire after seconds. example: 9000 refreshTokenExpTime: type: integer format: int32 description: The JWT can be refreshed during seconds. example: 604800 tokenIssuer: type: string description: The JWT issuer. example: thingsboard.io tokenSigningKey: type: string description: The JWT key is used to sing token. Base64 encoded. example: dkVTUzU2M2VMWUNwVVltTUhQU2o5SUM0Tkc3M0k2Ykdwcm85QTl6R0RaQ252OFlmVDk2OEptZXBNcndGeExFZg== AwsSnsSmsProviderConfiguration: allOf: - $ref: '#/components/schemas/SmsProviderConfiguration' - type: object properties: accessKeyId: type: string description: The AWS SNS Access Key ID. secretAccessKey: type: string description: The AWS SNS Access Key. region: type: string description: The AWS region. RepositorySettings: type: object description: A JSON value representing the Repository Settings. properties: repositoryUri: type: string authMethod: type: string enum: - USERNAME_PASSWORD - PRIVATE_KEY username: type: string password: type: string privateKeyFileName: type: string privateKey: type: string privateKeyPassword: type: string defaultBranch: type: string readOnly: type: boolean showMergeCommits: type: boolean localOnly: type: boolean UserPasswordPolicy: type: object properties: minimumLength: type: integer format: int32 description: Minimum number of symbols in the password. maximumLength: type: integer format: int32 description: Maximum number of symbols in the password. minimumUppercaseLetters: type: integer format: int32 description: Minimum number of uppercase letters in the password. minimumLowercaseLetters: type: integer format: int32 description: Minimum number of lowercase letters in the password. minimumDigits: type: integer format: int32 description: Minimum number of digits in the password. minimumSpecialCharacters: type: integer format: int32 description: Minimum number of special in the password. allowWhitespaces: type: boolean description: Allow whitespaces forceUserToResetPasswordIfNotValid: type: boolean description: Force user to update password if existing one does not pass validation passwordExpirationPeriodDays: type: integer format: int32 description: Password expiration period (days). Force expiration of the password. passwordReuseFrequencyDays: type: integer format: int32 description: Password reuse frequency (days). Disallow to use the same password for the defined number of days AutoVersionCreateConfig: type: object properties: saveRelations: type: boolean saveAttributes: type: boolean saveCredentials: type: boolean saveCalculatedFields: type: boolean branch: type: string SmsProviderConfiguration: discriminator: propertyName: type properties: type: type: string required: - type SystemInfoData: type: object properties: serviceId: type: string description: Service Id. serviceType: type: string description: Service type. cpuUsage: type: integer format: int64 description: CPU usage, in percent. cpuCount: type: integer format: int64 description: Total CPU usage. memoryUsage: type: integer format: int64 description: Memory usage, in percent. totalMemory: type: integer format: int64 description: Total memory in bytes. discUsage: type: integer format: int64 description: Disk usage, in percent. totalDiscSpace: type: integer format: int64 description: Total disc space in bytes. AdminSettingsId: 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: - ADMIN_SETTINGS example: ADMIN_SETTINGS required: - entityType - id SystemInfo: type: object properties: systemData: type: array description: System data. items: $ref: '#/components/schemas/SystemInfoData' monolith: type: boolean AdminSettings: type: object description: A JSON value representing the Mail Settings. properties: id: $ref: '#/components/schemas/AdminSettingsId' description: The Id of the Administration Settings, auto-generated, UUID createdTime: type: integer format: int64 description: Timestamp of the settings creation, in milliseconds example: 1609459200000 readOnly: true tenantId: $ref: '#/components/schemas/TenantId' description: JSON object with Tenant Id. readOnly: true key: type: string description: The Administration Settings key, (e.g. 'general' or 'mail') example: mail jsonValue: $ref: '#/components/schemas/JsonNode' description: JSON representation of the Administration Settings value AutoCommitSettings: type: object additionalProperties: $ref: '#/components/schemas/AutoVersionCreateConfig' UpdateMessage: type: object properties: updateAvailable: type: boolean description: '''True'' if new platform update is available.' currentVersion: type: string description: Current ThingsBoard version. latestVersion: type: string description: Latest ThingsBoard version. upgradeInstructionsUrl: type: string description: Upgrade instructions URL. currentVersionReleaseNotesUrl: type: string description: Current ThingsBoard version release notes URL. latestVersionReleaseNotesUrl: type: string description: Latest ThingsBoard version release notes URL. TestSmsRequest: type: object description: A JSON value representing the Test SMS request. properties: providerConfiguration: description: The SMS provider configuration oneOf: - $ref: '#/components/schemas/AwsSnsSmsProviderConfiguration' - $ref: '#/components/schemas/SmppSmsProviderConfiguration' - $ref: '#/components/schemas/TwilioSmsProviderConfiguration' numberTo: type: string description: The phone number or other identifier to specify as a recipient of the SMS. message: type: string description: The test message JsonNode: description: A value representing the any type (object or primitive) examples: - {} 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 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 SecuritySettings: type: object description: A JSON value representing the Security Settings. properties: passwordPolicy: $ref: '#/components/schemas/UserPasswordPolicy' description: The user password policy object. maxFailedLoginAttempts: type: integer format: int32 description: Maximum number of failed login attempts allowed before user account is locked. userLockoutNotificationEmail: type: string description: Email to use for notifications about locked users. mobileSecretKeyLength: type: integer format: int32 description: Mobile secret key length userActivationTokenTtl: type: integer format: int32 description: TTL in hours for user activation link maximum: 24 minimum: 1 passwordResetTokenTtl: type: integer format: int32 description: TTL in hours for password reset link maximum: 24 minimum: 1 required: - passwordResetTokenTtl - userActivationTokenTtl 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