openapi: 3.0.0
info:
  title: VDX Device Registration Service
  description: API description for VDX Device Registration Service.
  version: 0.1.28
  contact:
    email: development@kvalitetitsit.dk
tags:
  - name: Device Admin
    description: >-
      Device administration related API's. Security - OpenID Connect (OAuth2), i.e. requires header 'Authorization: Bearer \<token\>'.
  - name: Device Comm
    description: >-
      Device communication related API's. Security - OpenID Connect (OAuth2), i.e. requires header 'Authorization: Bearer \<token\>'.
  - name: Device Login
    description: Device login related API's. Security - see summary of endpoints.
servers: [{url: 'https://videoapi.vconf-stage.dk/devicereg'}]
paths:
  /v1/devices:
    get:
      security:
        - keycloakOIDC: []
      tags:
        - Device Admin
      parameters:
        - name: organisation_code
          in: query
          required: false
          description: Organisation code to filter devices by. Defaults to the organisation of the user.
          schema:
            type: string
        - name: include_suborganisations
          in: query
          required: false
          description: Whether to include devices from all suborganisations as well.
          schema:
            type: boolean
      summary: Get all devices from user context organisation.
      description: >-
        Get all devices from user context organisation. <br> The following values of the user role claim grants access: <br> * meeting-admin <br> * meeting-user <br> * meeting-planner <br> For roles meeting-user and meeting-planner, the token must additionally identify an existing device.
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/deviceResponse'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '502':
          $ref: '#/components/responses/502'
  /v1/device/{id}:
    get:
      security:
        - keycloakOIDC: []
      tags:
        - Device Admin
      parameters:
        - $ref: '#/components/parameters/uuid'
      summary: Get device with provided id. Only allowed to retrieve devices from own or sub organisations.
      description: >-
        Get device with provided id. Only allowed to retrieve devices from own or sub organisations. <br> The following values of the user role claim grants access: <br> * meeting-admin <br>
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/deviceResponse'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '502':
          $ref: '#/components/responses/502'
    delete:
      security:
        - keycloakOIDC: []
      tags:
        - Device Admin
      parameters:
        - $ref: '#/components/parameters/uuid'
      summary: Delete device with provided id. Only allowed to delete devices from own or sub organisations.
      description: >-
        Delete device with provided id. Only allowed to delete devices from own or sub organisations. <br> The following values of the user role claim grants access: <br> * meeting-admin <br>
      responses:
        '204':
          description: No content
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '500':
          $ref: '#/components/responses/500'
        '502':
          $ref: '#/components/responses/502'
    put:
      security:
        - keycloakOIDC: []
      tags:
        - Device Admin
      parameters:
        - $ref: '#/components/parameters/uuid'
      summary: Update device with provided id. Only allowed to update devices from own or sub organisations.
      description: >-
        Update device with provided id. Only allowed to update devices from own or sub organisations.<br> The following values of the user role claim grants access: <br> * meeting-admin <br>
      requestBody:
        description: device to update with
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/deviceRequest'
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/deviceResponse'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '409':
          $ref: '#/components/responses/409'
        '500':
          $ref: '#/components/responses/500'
        '502':
          $ref: '#/components/responses/502'
  /v1/device:
    post:
      security:
        - keycloakOIDC: []
      tags:
        - Device Admin
      summary: Create device. Only allowed to create devices within own or sub organisations.
      description: >-
        Create device. Only allowed to create devices within own or sub organisations. <br> The following values of the user role claim grants access: <br> * meeting-admin <br>
      requestBody:
        description: device details to use while adding
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/deviceRequest'
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/createDeviceResponse'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '409':
          $ref: '#/components/responses/409'
        '500':
          $ref: '#/components/responses/500'
        '502':
          $ref: '#/components/responses/502'
  /v1/device/{id}/password:
    get:
      security:
        - keycloakOIDC: []
      tags:
        - Device Admin
      parameters:
        - $ref: '#/components/parameters/uuid'
      summary: Generate new password for device with provided id. Only allowed for devices from own or sub organisations.
      description: >-
        Generate new password for device with provided id. Only allowed for devices from own or sub organisations. <br> The following values of the user role claim grants access: <br> * meeting-admin <br>
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/passwordOutput'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '502':
          $ref: '#/components/responses/502'
  /v1/heartbeat:
    get:
      security:
        - keycloakOIDC: []
      tags:
        - Device Comm
      summary: Endpoint for checking if device exists and is reachable
      description: Endpoint for checking if the device from provided JWT token exists and is reachable
      responses:
        '200':
          description: Ok
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '502':
          $ref: '#/components/responses/502'
  /v1/meetings:
    post:
      security:
        - keycloakOIDC: []
      tags:
        - Device Admin
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/createMeeting'
      summary: Create a meeting for a given device.
      description: >-
        Post meeting details for a given device to add it to the meeting list of said device. <br> The following values of the user role claim grants access: <br> * meeting-admin <br>
      responses:
        '204':
          description: No content
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
  /v1/meetings/{id}:
    delete:
      security:
        - keycloakOIDC: []
      tags:
        - Device Admin
      parameters:
        - $ref: '#/components/parameters/uuid'
      summary: Clear meeting queue of device with provided id. Only allowed to delete queues of devices from own or sub organisations.
      description: >-
        Clear meeting queue of device with provided id. Only allowed to delete queues of devices from own or sub organisations. <br> The following values of the user role claim grants access: <br> * meeting-admin <br>
      responses:
        '204':
          description: No content
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
  /v1/meeting:
    get:
      security:
        - keycloakOIDC: []
      tags:
        - Device Comm
      summary: Get the oldest unresolved meeting for a given device.
      description: >-
        Get the oldest unresolved meeting for device from provided JWT token. <br> The following values of the user role claim grants access: <br> * meeting-user <br> * meeting-planner <br>
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/meetingResponse'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
  /v1/messages:
    post:
      security:
        - keycloakOIDC: []
      tags:
        - Device Admin
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/createMessage'
      summary: Create a message for a given device.
      description: >-
        Post message details for a given device to add it to the message list of said device. <br> The following values of the user role claim grants access: <br> * meeting-admin <br>
      responses:
        '204':
          description: No content
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
  /v1/messages/{id}:
    delete:
      security:
        - keycloakOIDC: []
      tags:
        - Device Admin
      parameters:
        - $ref: '#/components/parameters/uuid'
      summary: Clear message queue of device with provided id. Only allowed to delete queues of devices from own or sub organisations.
      description: >-
        Clear message queue of device with provided id. Only allowed to delete queues of devices from own or sub organisations. <br> The following values of the user role claim grants access: <br> * meeting-admin <br>
      responses:
        '204':
          description: No content.
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
  /v1/message:
    get:
      security:
        - keycloakOIDC: []
      tags:
        - Device Comm
      summary: Get the oldest unresolved message for a given device.
      description: >-
        Get the oldest unresolved message for device from provided JWT token.<br> The following values of the user role claim grants access: <br> * meeting-user <br> * meeting-planner <br>
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/messageResponse'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
  /v1/one-click/{id}:
    get:
      security:
        - keycloakOIDC: []
      tags:
        - Device Login
      parameters:
        - $ref: '#/components/parameters/uuid'
        - name: client-id
          in: query
          description: Client id of client to be used when retrieving access token.
          required: true
          schema:
            type: string
          example: 'token-client'
      summary: >-
        Get a link for login of a given device. Security - OpenID Connect (OAuth2), i.e. requires header 'Authorization: Bearer \<token\>'.
      description: >-
        Generates a link for login of device with provided id. <br> The following values of the user role claim grants access: <br> * meeting-admin <br>
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/oneClickResponse'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '409':
          $ref: '#/components/responses/409'
        '500':
          $ref: '#/components/responses/500'
  /v1/login/{id}:
    get:
      tags:
        - Device Login
      parameters:
        - $ref: '#/components/parameters/loginId'
      summary: Get an access token for device with provided login id. Security - public endpoint.
      description: Get access token for device with provided login id.
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/accessToken'
        '404':
          $ref: '#/components/responses/404'
        '500':
          $ref: '#/components/responses/500'
        '502':
          $ref: '#/components/responses/502'
  /v1/device-login:
    post:
      tags:
        - Device Login
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/deviceCreationTokenLoginRequest'
      summary: Create device and get an access token for device. Security - public endpoint.
      description: >-
        Post device creation token to create simple device and retrieve access token. If name in body is not provided this will be set to the same as the generated short id. The organisation code can be set to a sub organisation of the owner of the device creation token. If not provided the device will be put in the organisation of which the device creation token belongs. <br> The following values of the user role claim grants access: <br> * meeting-admin <br>
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/accessToken'
        '400':
          $ref: '#/components/responses/400'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '409':
          $ref: '#/components/responses/409'
        '500':
          $ref: '#/components/responses/500'
        '502':
          $ref: '#/components/responses/502'
  /v1/device-creation-token:
    post:
      security:
        - keycloakOIDC: []
      tags:
        - Device Admin
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/deviceCreationTokenRequest'
      summary: Create a token for creating a device in a given organisation.
      description: >-
        Post organisation id for creation of a token to auto-create devices. <br> The following values of the user role claim grants access: <br> * meeting-admin <br>
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/deviceCreationToken'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '409':
          $ref: '#/components/responses/409'
        '500':
          $ref: '#/components/responses/500'
  /v1/device-creation-token/{organisation_code}:
    get:
      security:
        - keycloakOIDC: []
      tags:
        - Device Admin
      parameters:
        - $ref: '#/components/parameters/organisationCode'
      summary: Get token for auto-creating device in organisation.
      description: Get token for auto-creating device in provided organisation.
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/deviceCreationToken'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
components:
  securitySchemes:
    keycloakOIDC:
      type: oauth2
      description: >-
        OIDC security implemented by Keycloak. The token should contain a user role claim with at least one of the following values: <br> * meeting-admin <br> * meeting-user <br> * meeting-planner <br> * meeting-provisioner <br> * meeting-provisioner-user <br> <br> It is specified in the description of the endpoint which values grants access.
      flows:
        authorizationCode:
          authorizationUrl: https://login.vconf-stage.dk/auth/realms/broker/protocol/openid-connect/auth
          tokenUrl: https://login.vconf-stage.dk/auth/realms/broker/protocol/openid-connect/token
          scopes: {}
        clientCredentials:
          tokenUrl: https://login.vconf-stage.dk/auth/realms/broker/protocol/openid-connect/token
          scopes: {}
  parameters:
    organisationCode:
      name: organisation_code
      in: path
      description: organisation code
      required: true
      schema:
        type: string
      example: "device_org"
    loginId:
      name: id
      in: path
      description: a unique string for direct login
      required: true
      schema:
        type: string
      example: 2ObDwXazCYU-TEe3wPv2uw
    uuid:
      name: id
      in: path
      description: the uuid for the requested information
      required: true
      schema:
        type: string
        format: uuid
      example: 46b46a1e-a4d3-4387-87ee-a67dcaa222cb
  responses:
    '400':
      description: "Bad Request. This could be because: \n* One of the required parameters/properties are missing or is empty\n* Length of input is exceeding maximum length\n* Input is invalid\n(See a possible detailed error message in the in the response.)\n"
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/detailedError'
    '401':
      description: "Unauthorized. This could be because: \n* The calling system has not been properly authenticated.  \n* Part of user context is missing or cannot be parsed.\n* The provided JWT token is invalid.\n"
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/detailedError'
    '403':
      description: "Forbidden. This could be because: \n* The requested information does not belong the organisation of the user.\n* The device organisation is not a sub organisation of the user organisation.\n* The keycloak user does not match the device in the request.\n"
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/detailedError'
    '404':
      description: |
        Not Found. This could be because:
        * The device has not been created in the database.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/detailedError'
    '409':
      description: |
        Conflict. This could be because:
        * The generated short id was already in use.
        * The name of the device is already in use.
        * There has already been generated a device creation token for the organisation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/detailedError'
    '500':
      description: |
        Internal Server Error. This could be because:
        * Something went wrong when updating or deleting device in the database.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/detailedError'
    '502':
      description: |
        Bad Gateway. This could be because:
        * Something went wrong when creating, updating or deleting user in Keycloak.
        * The role of the device in Keycloak is invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/detailedError'
  schemas:
    deviceResponse:
      type: object
      required:
        - id
        - short_id
        - name
        - organisation_code
        - enabled
        - created_by
        - created_timestamp
        - updated_by
        - updated_timestamp
        - keycloak_id
      properties:
        id:
          description: Id of device.
          type: string
          format: uuid
          example: 46b46a1e-a4d3-4387-87ee-a67dcaa222cb
        short_id:
          description: Short id of device. This is also the username of the device in Keycloak.
          type: string
          example: "asdfghjk"
        name:
          description: Common name of device.
          type: string
          example: "Device Name"
        description:
          description: Description of device.
          type: string
          example: "This is a description."
        location:
          description: Location of device.
          type: string
          example: "device-location"
        organisation_code:
          description: The organisation the device belongs to.
          type: string
          example: "device_org"
        enabled:
          description: If the device is enabled in Keycloak or not.
          type: boolean
          example: false
        created_by:
          description: Who created the device.
          type: string
          example: "user@email.com"
        created_timestamp:
          description: When the device was created.
          type: string
          format: date-time
          example: "2024-06-10T10:34:41Z"
        updated_by:
          description: The last person to update the device.
          type: string
          example: "user@email.com"
        updated_timestamp:
          description: When the device was last updated.
          type: string
          format: date-time
          example: "2024-06-10T10:34:41Z"
        last_active_timestamp:
          description: When the device was last active.
          type: string
          format: date-time
          example: "2024-06-10T10:34:41Z"
        keycloak_id:
          description: User id of device in Keycloak.
          type: string
          format: uuid
          example: 46b46a1e-a4d3-4387-87ee-a67dcaa222cb
        role:
          $ref: '#/components/schemas/deviceRole'
        audiences:
          description: List of additional API's the device can access. A device can always access the device API.
          type: array
          items:
            type: string
    createDeviceResponse:
      allOf:
        - $ref: '#/components/schemas/deviceResponse'
        - type: object
          required:
            - keycloak_password
          properties:
            keycloak_password:
              description: Password of device in Keycloak.
              type: string
              example: "SuperSecretPassword123"
    deviceRequest:
      type: object
      required:
        - name
        - organisation_code
        - enabled
        - role
      properties:
        name:
          description: Common name of device.
          type: string
          example: "Device Name"
        description:
          description: Description of device.
          type: string
          example: "This is a description."
        location:
          description: Location of device.
          type: string
          maxLength: 250
          example: "device-location"
        organisation_code:
          description: The organisation the device belongs to.
          type: string
          example: "device_org"
        enabled:
          description: If the device should be enabled in Keycloak or not.
          type: boolean
          example: false
        role:
          $ref: '#/components/schemas/deviceRole'
        audiences:
          description: List of additional API's the device can access. A device can always access the device API.
          type: array
          items:
            type: string
    passwordOutput:
      type: object
      required:
        - id
        - short_id
        - name
        - keycloak_id
        - password
      properties:
        id:
          description: Id of device.
          type: string
          format: uuid
          example: 46b46a1e-a4d3-4387-87ee-a67dcaa222cb
        short_id:
          description: Short id of device. This is also the username of the device in Keycloak.
          type: string
          example: "asdfghjk"
        name:
          description: Common name of device.
          type: string
          example: "Device Name"
        keycloak_id:
          description: User id of device in Keycloak.
          type: string
          format: uuid
          example: 46b46a1e-a4d3-4387-87ee-a67dcaa222cb
        password:
          description: Password of device in Keycloak.
          type: string
          example: "SuperSecretPassword123"
    createMeeting:
      type: object
      required:
        - device_id
        - uri
        - pin
        - meeting_type
      properties:
        device_id:
          description: Id of device.
          type: string
          format: uuid
          example: 46b46a1e-a4d3-4387-87ee-a67dcaa222cb
        uri:
          description: Uri of meeting without domain
          type: string
          example: 574893
          maxLength: 100
        pin:
          description: Pin of meeting
          type: integer
          format: int32
          minimum: 1000
          maximum: 999999999
          example: 12345
        meeting_type:
          description: Type of meeting
          type: string
          example: "oneway-nosound"
          maxLength: 36
        meeting_host:
          description: Meeting host
          type: string
          example: "host"
          maxLength: 100
        meeting_description:
          description: Description of meeting
          type: string
          example: "A very important meeting"
          maxLength: 5000
    meetingResponse:
      type: object
      required:
        - status
      properties:
        status:
          description: Indicates if a waiting meeting has been found or not.
          type: string
          enum: [MEETING_FOUND, NO_WAITING_MEETINGS]
        meeting:
          $ref: '#/components/schemas/meeting'
    meeting:
      type: object
      required:
        - uri
        - pin
        - meeting_type
      properties:
        uri:
          description: Uri of meeting without domain
          type: string
          example: 574893
          maxLength: 100
        pin:
          description: Pin of meeting
          type: integer
          format: int32
          minimum: 1000
          maximum: 999999999
          example: 12345
        meeting_type:
          description: Type of meeting
          type: string
          example: "oneway-nosound"
          maxLength: 36
        meeting_host:
          description: Meeting host
          type: string
          example: "host"
          maxLength: 100
        meeting_description:
          description: Description of meeting
          type: string
          example: "A very important meeting"
          maxLength: 5000
    createMessage:
      type: object
      required:
        - device_id
        - key
        - value
      properties:
        device_id:
          description: Id of device.
          type: string
          format: uuid
          example: 46b46a1e-a4d3-4387-87ee-a67dcaa222cb
        key:
          description: Type of message
          type: string
          example: "String message"
        value:
          description: Message object
          type: object
          example: "This is a string example"
    messageResponse:
      type: object
      required:
        - status
      properties:
        status:
          description: Indicates if a waiting message has been found or not.
          type: string
          enum: [MESSAGE_FOUND, NO_WAITING_MESSAGES]
        message:
          $ref: '#/components/schemas/message'
    message:
      type: object
      required:
        - key
        - value
      properties:
        key:
          description: Type of message
          type: string
          example: "String message"
        value:
          description: Message object
          type: object
          example: "This is a string example"
    oneClickResponse:
      type: object
      required:
        - link
      properties:
        link:
          description: One-click link for accessing some given device
          type: string
          format: uri
          example: "http://localhost:8080/v1/login/unique-login-id"
    accessToken:
      type: object
      properties:
        access_token:
          description: Valid access token
          type: string
          example: "ey..."
        expires_in:
          description: For how long the access token is valid
          type: integer
          format: int64
          example: 300
        refresh_expires_in:
          description: For how long the refresh token is valid
          type: integer
          format: int64
          example: 300
        refresh_token:
          description: Valid refresh token
          type: string
          example: "ey..."
        token_type:
          description: Type of token
          type: string
          example: "Bearer"
        not-before-policy:
          description: Not before policy
          type: integer
          example: 0
        session_state:
          description: Session state, string identifier for session
          type: string
          example: "3ec5215f-7cc2-49ce-8dcf-8605d037c2d7"
        scope:
          description: Scope of token
          type: string
          example: "profile email"
    deviceRole:
      type: string
      description: Role granted device for keycloak token.
      example: "MEETING_USER"
      enum:
        - MEETING_USER
        - MEETING_PLANNER
    deviceCreationTokenRequest:
      type: object
      required:
        - organisation_code
        - client_id
      properties:
        organisation_code:
          type: string
          description: organisation code for device
          example: "device_org"
        client_id:
          type: string
          description: Client id of client to be used when retrieving access token.
          example: "token-client"
    deviceCreationToken:
      type: object
      properties:
        deviceCreationToken:
          type: string
          format: uuid
          description: token belonging to organisation to auto-create devices
          example: 46b46a1e-a4d3-4387-87ee-a67dcaa222cb
    deviceCreationTokenLoginRequest:
      allOf:
        - $ref: '#/components/schemas/deviceCreationToken'
        - type: object
          required:
            - deviceCreationToken
          properties:
            name:
              description: Common name of device. If not provided this will be the same as short id.
              type: string
              example: "Device Name"
            organisation_code:
              description: The organisation the device belongs to. If not provided this will be the same as create-device-token belongs to.
              type: string
              example: "device_org"
    detailedError:
      allOf:
        - $ref: '#/components/schemas/basicError'
        - type: object
          required:
            - detailed_error
            - detailed_error_code
          properties:
            detailed_error:
              description: Detailed error text. This could be a text describing a validation error.
              type: string
            detailed_error_code:
              description: 10 - Keycloak error, device was not created; 11 - Keycloak error, device was not updated; 12 - Keycloak error, device was not deleted; 13 - Keycloak error, password was not updated; 14 - Database error, not found; 15 - Database error, not created; 16 - Database error, not updated; 17 - Database error, not deleted; 18 - Validation error, user organisation code is not in parent organisation tree of organisation in request; 19 - Validation error, failed to retrieve user context; 20 - Duplicate key, the generated short id or login id was already allocated, try creating device/getting login link again; 21 - Duplicate key, an entry in the database already has one or more of the requested values; 22 - Validation error, keycloak user and requested device does not match; 23 - Keycloak error, failed to retrieve access token; 24 - Validation error, input validation failed; 25 - Keycloak error, failed to find valid role attribute of device in Keycloak; 26 - Keycloak error, failed to find device or device attributes in Keycloak; 27 - Keycloak error, failed to retrieve device API access token;
              type: string
              enum:
                - 10
                - 11
                - 12
                - 13
                - 14
                - 15
                - 16
                - 17
                - 18
                - 19
                - 20
                - 21
                - 22
                - 23
                - 24
                - 25
                - 26
                - 27
    basicError:
      type: object
      required:
        - timestamp
        - status
        - error
        - path
      properties:
        error:
          description: Error message.
          type: string
        path:
          description: Path
          type: string
        status:
          description: HTTP status code
          type: integer
        timestamp:
          description: Time of error
          type: string
          format: date-time