Diebold Nixdorf TM Authorization API

openapi: 3.2.0
info:
  title: DN TM Authorization TM Authorization API
  description: Public TM Authorization API of Diebold Nixdorf to access the Transaction Middleware.
  version: 1.8.1
  contact:
    email: thorsten.brinkmann@dieboldnixdorf.com
servers:
- url: http://localhost:8080/oauth-api/v1
- url: https://localhost:8080/oauth-api/v1
tags:
- name: TM Authorization API
paths:
  /tm-authorization/authenticate:
    post:
      tags:
      - TM Authorization API
      summary: An endpoint to authenticate a user
      description: 'An endpoint to authenticates an user and returns on success a JWT token for all further requests.


        The access token is valid for 1 hour, if not set to a different value in the TM configuration.


        The user will be logged in and his initial hierarchy will be loaded.


        ATTENTION:


        The delivered access token has to be used in the Authorization header attribute of all further requests.


        Moreover, a header attribute nodeID must be set with the value of the desired node in all further requests!


        Please see: $ref: ''#/components/parameters/nodeID-Param''


        Moreover, together with the access token some other information are returned in the response such as the root node hierarchy, granted rights etc..'
      operationId: tm-authenticate
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TmAuthenticationRequest'
      responses:
        '200':
          description: 'Th user has been authenticated.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TmAuthenticationResponse'
              example:
                state: OK
                jwt: ey..5c
        '400':
          $ref: '#/components/responses/BadRequest400'
        '401':
          $ref: '#/components/responses/Unauthorized401'
        '500':
          $ref: '#/components/responses/InternalServerError500'
  /tm-authorization/logout:
    delete:
      tags:
      - TM Authorization API
      operationId: tm-logout
      security:
      - bearerAuth: []
      summary: An endpoint to logout an already authenticated user
      description: An endpoint to logout an already authenticated user.
      responses:
        '200':
          description: OK
        '400':
          $ref: '#/components/responses/BadRequest400'
        '401':
          $ref: '#/components/responses/Unauthorized401'
        '500':
          $ref: '#/components/responses/InternalServerError500'
  /tm-authorization/keys:
    get:
      tags:
      - TM Authorization API
      summary: An endpoint to get the public keys to verify the JWT token
      description: An endpoint to get the public keys to verify the JWT token.
      operationId: tm-get-keys
      responses:
        '200':
          description: 'Th user has been authenticated.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TmGetKeysResponse'
        '400':
          $ref: '#/components/responses/BadRequest400'
        '500':
          $ref: '#/components/responses/InternalServerError500'
components:
  responses:
    Unauthorized401:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    InternalServerError500:
      description: Internal Server Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest400:
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    TmGetKeysResponse:
      type: object
      required:
      - keys
      properties:
        keys:
          type: array
          items:
            $ref: '#/components/schemas/TmKeyInfo'
    TmKeyInfo:
      type: object
      required:
      - kty
      - use
      - alg
      - kid
      properties:
        kty:
          type: string
          enum:
          - RSA
          - EC
          description: Key Type. Indicates the cryptographic algorithm family (e.g., RSA, EC for Elliptic Curve).
          example: RSA
        use:
          type: string
          enum:
          - sig
          - enc
          description: Public Key Use. The usage type of the key. Indicates either a signature verification key or a key which is used for encryption.
          example: sig
        alg:
          type: string
          description: 'Algorithm. The specific algorithm intended for use with this key (e.g., RS256 for RSA with SHA-256) or

            ES256 for Elliptic Curve using P-256 and SHA-256.

            '
          example: ES256
        kid:
          type: string
          description: Key ID. A unique identifier for this specific key. This is crucial because OPs often have multiple keys in rotation.
          example: xyz789uvw000
        issuer:
          type: string
          description: 'The issuer of the key.

            '
          example: http://localhost:8080/oauth-api/v1
        n:
          type: string
          description: The modulus of an RSA public key.
          example: 0vx7B...aBc2
        e:
          type: string
          description: The exponent of an RSA public key.
          example: AQAB
        crv:
          type: string
          description: The curve of an Elliptic Curve public key.
          example: P-384
        x:
          type: string
          description: The x coordinate of an Elliptic Curve public key. (base64url encoded)
          example: z8J91yVzE6..._Nf0dQ7E7YnBd7g
        y:
          type: string
          description: The y coordinate of an Elliptic Curve public key. (base64url encoded)
          example: pZ_2dqtMh7M..._k9blCwC6nQ
    TmAuthenticationResponse:
      type: object
      description: 'Describes the response of the authentication request.

        '
      required:
      - state
      - message
      properties:
        status:
          type: string
          enum:
          - OK
          - FAILED
        message:
          type: string
          description: 'Description of what went wrong.

            '
        jwt:
          type: string
          format: JSON Web Token
          description: 'After successful authentication a JSON Web Token is returned for further requests

            '
        userName:
          type: string
          description: 'The display name of the current user.

            '
        userLocale:
          type: string
          description: 'The locale of the current user.

            '
        userTimeZone:
          type: string
          description: 'The timezone name of the current user.

            '
        rootNodeIDs:
          type: array
          items:
            type: string
            description: 'The root node IDs of the current user.

              '
        rootNodeType:
          type: string
          description: 'The type of the root node of the user''s hierarchy.

            '
        rights:
          description: 'The rights list of the current user.

            '
          type: array
          items:
            $ref: '#/components/schemas/TmRight'
    TmAuthenticationRequest:
      type: object
      required:
      - username
      - password
      properties:
        username:
          type: string
          description: name of the user to authenticate
          example: qauser
        password:
          type: string
          format: base64
          description: password base64 encoded
          example: base64-encode(my-password)
        language:
          type: string
          format: ISO 639
          description: 'sets the language for this session. This will override the "Accept-Language" HTTP header.

            '
          example: de
        timezone:
          type: string
          format: tz database
          description: 'set the timezone for this session.

            '
          example: Europe/Berlin
        country:
          type: string
          format: ISO 3166-1
          description: 'The time zone is determined based on the country if the timezone attribute is not set.

            '
          example: DE
    Error:
      description: "The error property is optional.<br< \nIt is set only if an error has been detected.\n"
      type: object
      properties:
        message:
          description: An optional, additional message which describes the error.
          type: string
          maxLength: 256
          example: Unauthorized
        errorCode:
          description: An error code as outlined in the PI-API documentation.
          type: string
          example: REQUEST_DATA_INVALID_ID
    TmRight:
      type: object
      description: 'Describes a right as integer values as well as in a readable form.

        '
      required:
      - rightId
      - rightName
      properties:
        rightId:
          type: string
          description: 'The id of the right.

            '
        rightName:
          type: string
          description: 'The right in a human readable form.

            '
        rightDescription:
          type: string
          description: 'The description of the right in a human readable form.

            '
  securitySchemes:
    basicAuth:
      type: http
      description: 'When using the basic authentication method, the base64 username and password must be specified in the HTTP authorization header - which is not recommended at all and should only be used for testing purposes during development time.

        '
      scheme: basic
    bearerAuth:
      type: http
      description: 'When using the bearer authentication method an access token has to be provided in the HTTP authorization header

        '
      scheme: bearer
externalDocs:
  description: Find out more about Swagger
  url: https://swagger.io