ThingsBoard
ThingsBoard tenant-controller API

Tenant
Documentation GitHub OpenAPI
OpenAPI Specification

openapi: 3.1.0
info:
  title: ThingsBoard Admin admin-controller tenant-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: tenant-controller
  description: Tenant
paths:
  /api/tenant:
    post:
      tags:
      - tenant-controller
      summary: Create or Update Tenant (saveTenant)
      description: 'Create or update the Tenant. When creating tenant, platform generates Tenant Id as [time-based UUID](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_1_(date-time_and_MAC_address)). Default Rule Chain and Device profile are also generated for the new tenants automatically. The newly created Tenant Id will be present in the response. Specify existing Tenant Id id to update the Tenant. Referencing non-existing Tenant Id will cause ''Not Found'' error.Remove ''id'', ''tenantId'' from the request body example (below) to create new Tenant entity.


        Available for users with ''SYS_ADMIN'' authority.'
      operationId: saveTenant
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Tenant'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Tenant'
  /api/tenants:
    get:
      tags:
      - tenant-controller
      summary: Get Tenants (getTenants)
      description: "Returns a page of tenants registered in the platform. 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: getTenantsByIds
      parameters:
      - name: tenantIds
        in: query
        description: A list of tenant 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 tenant name.
        required: false
        schema:
          type: string
      - name: sortProperty
        in: query
        description: Property of entity to sort by
        required: false
        schema:
          type: string
          enum:
          - createdTime
          - title
          - email
          - country
          - state
          - city
          - address
          - address2
          - zip
          - phone
          - 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/PageDataTenant'
                - type: array
                  items:
                    $ref: '#/components/schemas/Tenant'
  /api/tenantInfos:
    get:
      tags:
      - tenant-controller
      summary: Get Tenants Info (getTenants)
      description: "Returns a page of tenant info objects registered in the platform. The Tenant Info object extends regular Tenant object and includes Tenant Profile name. 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: getTenantInfos
      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 tenant name.
        required: false
        schema:
          type: string
      - name: sortProperty
        in: query
        description: Property of entity to sort by
        required: false
        schema:
          type: string
          enum:
          - createdTime
          - tenantProfileName
          - title
          - email
          - country
          - state
          - city
          - address
          - address2
          - zip
          - phone
          - 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/PageDataTenantInfo'
  /api/tenant/{tenantId}:
    get:
      tags:
      - tenant-controller
      summary: Get Tenant (getTenantById)
      description: "Fetch the Tenant object based on the provided Tenant Id. \n\nAvailable for users with 'SYS_ADMIN' or 'TENANT_ADMIN' authority."
      operationId: getTenantById
      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
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Tenant'
    delete:
      tags:
      - tenant-controller
      summary: Delete Tenant (deleteTenant)
      description: 'Deletes the tenant, it''s customers, rule chains, devices and all other related entities. Referencing non-existing tenant Id will cause an error.


        Available for users with ''SYS_ADMIN'' or ''TENANT_ADMIN'' authority.'
      operationId: deleteTenant
      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
      responses:
        '200':
          description: OK
  /api/tenant/info/{tenantId}:
    get:
      tags:
      - tenant-controller
      summary: Get Tenant Info (getTenantInfoById)
      description: "Fetch the Tenant Info object based on the provided Tenant Id. The Tenant Info object extends regular Tenant object and includes Tenant Profile name. \n\nAvailable for users with 'SYS_ADMIN' or 'TENANT_ADMIN' authority."
      operationId: getTenantInfoById
      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
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TenantInfo'
components:
  schemas:
    JsonNode:
      description: A value representing the any type (object or primitive)
      examples:
      - {}
    TenantProfileId:
      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_PROFILE
          example: TENANT_PROFILE
      required:
      - entityType
      - id
    Tenant:
      type: object
      description: A JSON value representing the tenant.
      properties:
        id:
          $ref: '#/components/schemas/TenantId'
          description: JSON object with the tenant Id. Specify this field to update the tenant. Referencing non-existing tenant Id will cause error. Omit this field to create new tenant.
        createdTime:
          type: integer
          format: int64
          description: Timestamp of the tenant creation, in milliseconds
          example: 1609459200000
          readOnly: true
        country:
          type: string
          description: Country
          example: US
        state:
          type: string
          description: State
          example: NY
        city:
          type: string
          description: City
          example: New York
        address:
          type: string
          description: Address Line 1
          example: 42
        address2:
          type: string
          description: Address Line 2
        zip:
          type: string
          description: Zip code
          example: 10004
        phone:
          type: string
          description: Phone number
          example: +1(415)777-7777
        email:
          type: string
          description: Email
          example: example@company.com
        title:
          type: string
          description: Title of the tenant
          example: Company A
        region:
          type: string
          description: Geo region of the tenant
          example: North America
        tenantProfileId:
          $ref: '#/components/schemas/TenantProfileId'
          description: JSON object with Tenant Profile Id
        version:
          type: integer
          format: int64
        name:
          type: string
          description: Name of the tenant. Read-only, duplicated from title for backward compatibility
          example: Company A
          readOnly: true
        additionalInfo:
          $ref: '#/components/schemas/JsonNode'
          description: Additional parameters of the device
      required:
      - title
    TenantInfo:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/TenantId'
          description: JSON object with the tenant Id. Specify this field to update the tenant. Referencing non-existing tenant Id will cause error. Omit this field to create new tenant.
        createdTime:
          type: integer
          format: int64
          description: Timestamp of the tenant creation, in milliseconds
          example: 1609459200000
          readOnly: true
        country:
          type: string
          description: Country
          example: US
        state:
          type: string
          description: State
          example: NY
        city:
          type: string
          description: City
          example: New York
        address:
          type: string
          description: Address Line 1
          example: 42
        address2:
          type: string
          description: Address Line 2
        zip:
          type: string
          description: Zip code
          example: 10004
        phone:
          type: string
          description: Phone number
          example: +1(415)777-7777
        email:
          type: string
          description: Email
          example: example@company.com
        title:
          type: string
          description: Title of the tenant
          example: Company A
        region:
          type: string
          description: Geo region of the tenant
          example: North America
        tenantProfileId:
          $ref: '#/components/schemas/TenantProfileId'
          description: JSON object with Tenant Profile Id
        version:
          type: integer
          format: int64
        tenantProfileName:
          type: string
          description: Tenant Profile name
          example: Default
        name:
          type: string
          description: Name of the tenant. Read-only, duplicated from title for backward compatibility
          example: Company A
          readOnly: true
        additionalInfo:
          $ref: '#/components/schemas/JsonNode'
          description: Additional parameters of the device
      required:
      - title
    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
    PageDataTenant:
      type: object
      properties:
        data:
          type: array
          description: Array of the entities
          items:
            $ref: '#/components/schemas/Tenant'
          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
    PageDataTenantInfo:
      type: object
      properties:
        data:
          type: array
          description: Array of the entities
          items:
            $ref: '#/components/schemas/TenantInfo'
          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 <your_api_key_value>**


        Example: **ApiKey tb_5te51SkLRYpjGrujUGwqkjFvooWBlQpVe2An2Dr3w13wjfxDW**


        <br>**NOTE**: Use only ONE authentication method at a time. If both are authorized, JWT auth takes the priority.<br>

        '
      name: X-Authorization
      in: header
ThingsBoard tenant-controller API

Documentation

Specifications

Schemas & Data

OpenAPI Specification
