openapi: 3.2.0
info:
  title: ThingsBoard REST Two Factor Auth Config Controller API
  description: ThingsBoard open-source IoT platform REST API documentation.
  contact:
    name: ThingsBoard team
    url: https://thingsboard.io
    email: info@thingsboard.io
  license:
    name: Apache License Version 2.0
    url: https://github.com/thingsboard/thingsboard/blob/master/LICENSE
  version: 3.7.0
servers:
- url: https://vista.viridiparente.com
  description: Generated server url
tags:
- name: two-factor-auth-config-controller
paths:
  /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.

        Update request example:

        ```

        {

        "useByDefault": true

        }

        ```

        Returns whole account''s 2FA settings object.


        Available 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.


        Returns whole account''s 2FA settings object.

        Will throw an error (Bad Request) if the provider is not configured for usage.


        Available 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.

        Returns whole account''s 2FA settings object.


        Available 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/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:

        - `providers` - the list of 2FA providers'' configs. Users will only be allowed to use 2FA providers from this list.


        - `minVerificationCodeSendPeriod` - minimal period in seconds to wait after verification code send request to send next request.

        - `verificationCodeCheckRateLimit` - rate limit configuration for verification code checking.

        The format is standard: ''amountOfRequests:periodInSeconds''. The value of ''1:60'' would limit verification code checking requests to one per minute.

        - `maxVerificationFailuresBeforeUserLockout` - maximum number of verification failures before a user gets disabled.

        - `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.


        TOTP 2FA provider config has following settings:

        - `issuerName` - issuer name that will be displayed in an authenticator app near a username. Must not be blank.


        For SMS 2FA provider:

        - `smsVerificationMessageTemplate` - verification message template. Available template variables are ${code} and ${userEmail}. It must not be blank and must contain verification code variable.

        - `verificationCodeLifetime` - verification code lifetime in seconds. Required to be positive.


        For EMAIL provider type:

        - `verificationCodeLifetime` - the same as for SMS.


        Example of the settings:

        ```

        {

        "providers": [

        {

        "providerType": "TOTP",

        "issuerName": "TB"

        },

        {

        "providerType": "EMAIL",

        "verificationCodeLifetime": 60

        },

        {

        "providerType": "SMS",

        "verificationCodeLifetime": 60,

        "smsVerificationMessageTemplate": "Here is your verification code: ${code}"

        }

        ],

        "minVerificationCodeSendPeriod": 60,

        "verificationCodeCheckRateLimit": "3:900",

        "maxVerificationFailuresBeforeUserLockout": 10,

        "totalAllowedTimeForVerification": 600

        }

        ```


        Available 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.


        Example of EMAIL 2FA account config:

        ```

        {

        "providerType": "EMAIL",

        "useByDefault": true,

        "email": "separate-email-for-2fa@thingsboard.org"

        }

        ```


        Example of SMS 2FA account config:

        ```

        {

        "providerType": "SMS",

        "useByDefault": false,

        "phoneNumber": "+38012312321"

        }

        ```


        For TOTP this method does nothing.


        Will throw an error (Bad Request) if submitted account config is not valid, or if the provider is not configured for usage.


        Available 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.


        For TOTP, this will return a corresponding account config template with a generated OTP auth URL (with new random secret key for each API call) that can be then converted to a QR code to scan with an authenticator app. Example:

        ```

        {

        "providerType": "TOTP",

        "useByDefault": false,

        "authUrl": "otpauth://totp/TB%202FA:tenant@thingsboard.org?issuer=TB+2FA&secret=PNJDNWJVAK4ZTUYT7RFGPQLXA7XGU7PX"

        }

        ```


        For EMAIL, the generated config will contain email from user''s account:

        ```

        {

        "providerType": "EMAIL",

        "useByDefault": false,

        "email": "tenant@thingsboard.org"

        }

        ```


        For SMS 2FA this method will just return a config with empty/default values as there is nothing to generate/preset:

        ```

        {

        "providerType": "SMS",

        "useByDefault": false,

        "phoneNumber": null

        }

        ```


        Will throw an error (Bad Request) if the provider is not configured for usage.


        Available for any authorized user.'
      operationId: generateTwoFaAccountConfig
      parameters:
      - name: providerType
        in: query
        description: 2FA provider type to generate new account config for
        required: true
        schema:
          default: TOTP
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/BackupCodeTwoFaAccountConfig'
                - $ref: '#/components/schemas/EmailTwoFaAccountConfig'
                - $ref: '#/components/schemas/SmsTwoFaAccountConfig'
                - $ref: '#/components/schemas/TotpTwoFaAccountConfig'
  /api/2fa/providers:
    get:
      tags:
      - two-factor-auth-config-controller
      summary: Get available 2FA providers (getAvailableTwoFaProviders)
      description: 'Get the list of provider types available for user to use (the ones configured by tenant or sysadmin).

        Example of response:

        ```

        [

        "TOTP",

        "EMAIL",

        "SMS"

        ]

        ```


        Available for any authorized user.'
      operationId: getAvailableTwoFaProviders_1
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
                  enum:
                  - TOTP
                  - SMS
                  - EMAIL
                  - BACKUP_CODE
  /api/2fa/account/settings:
    get:
      tags:
      - two-factor-auth-config-controller
      summary: Get account 2FA settings (getAccountTwoFaSettings)
      description: 'Get user''s account 2FA configuration. Configuration contains configs for different 2FA providers.


        Example:

        ```

        {

        "configs": {

        "EMAIL": {

        "providerType": "EMAIL",

        "useByDefault": true,

        "email": "tenant@thingsboard.org"

        },

        "TOTP": {

        "providerType": "TOTP",

        "useByDefault": false,

        "authUrl": "otpauth://totp/TB%202FA:tenant@thingsboard.org?issuer=TB+2FA&secret=P6Z2TLYTASOGP6LCJZAD24ETT5DACNNX"

        },

        "SMS": {

        "providerType": "SMS",

        "useByDefault": false,

        "phoneNumber": "+380501253652"

        }

        }

        }

        ```


        Available for any authorized user.'
      operationId: getAccountTwoFaSettings
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountTwoFaSettings'
components:
  schemas:
    EmailTwoFaAccountConfig:
      allOf:
      - $ref: '#/components/schemas/TwoFaAccountConfig'
      - type: object
        properties:
          email:
            type: string
      required:
      - email
    TwoFaAccountConfigUpdateRequest:
      properties:
        useByDefault:
          type: boolean
    BackupCodeTwoFaAccountConfig:
      allOf:
      - $ref: '#/components/schemas/TwoFaAccountConfig'
      - type: object
        properties:
          codes:
            type: array
            items:
              type: string
            uniqueItems: true
          codesLeft:
            type: integer
            format: int32
      required:
      - codes
    TwoFaProviderConfig:
      discriminator:
        propertyName: providerType
      properties:
        providerType:
          type: string
      required:
      - providerType
    SmsTwoFaProviderConfig:
      allOf:
      - $ref: '#/components/schemas/TwoFaProviderConfig'
      - type: object
        properties:
          verificationCodeLifetime:
            type: integer
            format: int32
            minimum: 1
          smsVerificationMessageTemplate:
            type: string
            pattern: .*\$\{code}.*
      required:
      - smsVerificationMessageTemplate
    SmsTwoFaAccountConfig:
      allOf:
      - $ref: '#/components/schemas/TwoFaAccountConfig'
      - type: object
        properties:
          phoneNumber:
            type: string
            pattern: ^\+[1-9]\d{1,14}$
      required:
      - phoneNumber
    TwoFaAccountConfig:
      discriminator:
        propertyName: providerType
      properties:
        useByDefault:
          type: boolean
        providerType:
          type: string
      required:
      - providerType
    TotpTwoFaProviderConfig:
      allOf:
      - $ref: '#/components/schemas/TwoFaProviderConfig'
      - type: object
        properties:
          issuerName:
            type: string
      required:
      - issuerName
    TotpTwoFaAccountConfig:
      allOf:
      - $ref: '#/components/schemas/TwoFaAccountConfig'
      - type: object
        properties:
          authUrl:
            type: string
            pattern: otpauth://totp/(\S+?):(\S+?)\?issuer=(\S+?)&secret=(\w+?)
      required:
      - authUrl
    EmailTwoFaProviderConfig:
      allOf:
      - $ref: '#/components/schemas/TwoFaProviderConfig'
      - type: object
        properties:
          verificationCodeLifetime:
            type: integer
            format: int32
            minimum: 1
    BackupCodeTwoFaProviderConfig:
      allOf:
      - $ref: '#/components/schemas/TwoFaProviderConfig'
      - type: object
        properties:
          codesQuantity:
            type: integer
            format: int32
            minimum: 1
    AccountTwoFaSettings:
      properties:
        configs:
          type: object
          additionalProperties:
            oneOf:
            - $ref: '#/components/schemas/BackupCodeTwoFaAccountConfig'
            - $ref: '#/components/schemas/EmailTwoFaAccountConfig'
            - $ref: '#/components/schemas/SmsTwoFaAccountConfig'
            - $ref: '#/components/schemas/TotpTwoFaAccountConfig'
    PlatformTwoFaSettings:
      description: Settings value
      properties:
        providers:
          type: array
          items:
            oneOf:
            - $ref: '#/components/schemas/BackupCodeTwoFaProviderConfig'
            - $ref: '#/components/schemas/EmailTwoFaProviderConfig'
            - $ref: '#/components/schemas/SmsTwoFaProviderConfig'
            - $ref: '#/components/schemas/TotpTwoFaProviderConfig'
        minVerificationCodeSendPeriod:
          type: integer
          format: int32
          minimum: 5
        verificationCodeCheckRateLimit:
          type: string
          pattern: '[1-9]\d*:[1-9]\d*'
        maxVerificationFailuresBeforeUserLockout:
          type: integer
          format: int32
          minimum: 0
        totalAllowedTimeForVerification:
          type: integer
          format: int32
          minimum: 60
      required:
      - minVerificationCodeSendPeriod
      - providers
      - totalAllowedTimeForVerification
  securitySchemes:
    HTTP_login_form:
      type: http
      description: Enter Username / Password
      scheme: loginPassword
      bearerFormat: /api/auth/login|X-Authorization