DN TM Authorization API

openapi: 3.0.3
info:
  title: DN 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
tags:
- name: DN TM Authorization API
  description: 'Public TM Authorization API of Diebold Nixdorf to access the Transaction Middleware.

    '
  externalDocs:
    description: Find out more
    url: https://dieboldnixdorf.com
externalDocs:
  description: Find out more about Swagger
  url: https://swagger.io
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.<br>

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

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

        <font color=''red''><b>ATTENTION:</b></font><br>

        The delivered access token has to be used in the <b><l>Authorization</l></b> header attribute of all further requests.<br>

        Moreover, a header attribute <font color=''red''><b><l>nodeID</l></b></font> must be set with the value of the desired
        node in all further requests!<br>

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

        Moreover, together with the access token some other information are returned in the response such as the root node
        hierarchy, granted rights etc..<br>

        '
      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'
  /authorization/login:
    get:
      tags:
      - TM OAuth API
      operationId: login
      summary: Get redirected to the authorisation URL or retrieve the list of external authorisation systems.
      description: "Retrieve the list of  external authorisation systems.<br>\nIt contains an array of authorisation URLs\
        \ as well as their display names.<br>\nAn authorisation URL contains state, nonce, login redirect URL and other things.<br>\n\
        The login redirect URL contains also the <i>authentication_redirection_endpoint</i> in the \nparameter <b><l>redirect_uri</b></l>,\
        \ which <font color='red'>must never</font> be called directly.<br>\nFor more information on the <b>final result of\
        \ the authorization process</b>, see the response from the endpoint /authorization.<br>\n"
      parameters:
      - in: query
        name: login_hint
        required: false
        schema:
          type: string
        description: 'An optional parameter which maybe contains a user name or something like that.<br>

          This parameter will be added to the <b><l>redirect_url</b></l> as an "application/x-www-form-urlencoded" formatted
          query component.

          '
      - in: query
        name: tenant
        required: false
        schema:
          type: string
        description: "An optional parameter which contains the tenant id.<br>\nThis parameter will be added to the <b><l>redirect_url</b></l>\
          \ as an \"application/x-www-form-urlencoded\" formatted query component.<br>\nThis parameter is also used - if given\
          \ - to find out which authentication server should be used, if there are more than one \nauthentication server configured\
          \ in the system.\n"
      responses:
        '200':
          description: 'Returns an array of AuthenticationProviderData.

            '
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AuthenticationProviderData'
        '500':
          $ref: '#/components/responses/InternalServerError500'
  /authorization:
    post:
      summary: Do NOT call this endpoint.
      description: 'This end point is the redirection endpoint as given in the <b><l>redirect_url</b></l> of the authorization
        request.<br>

        <font color=''red''><b>Do NOT call this endpoint directly</b></font>, because it''s called by the authorization server
        via http 302 redirect.

        '
      operationId: authenticationRedirectionEndpoint
      tags:
      - TM OAuth API
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
              - code
              - state
              properties:
                code:
                  type: string
                state:
                  type: string
      responses:
        '200':
          description: 'Returns the TokenResponseData, which contains the access token, refresh token, expiresIn and token
            type.<br>

            <br>

            At this point, the user is already logged in and their original hierarchy has been loaded.<br>

            <font color=''red''><b>ATTENTION:</b></font><br>

            The delivered access token has to be used in the <b><l>Authorization</l></b> header attribute <b>of all further
            requests</b>.<br>

            Moreover, a header attribute <font color=''red''><b><l>nodeID</l></b></font> must be set with the value of the
            desired node in all further requests!<br>

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

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenResponseData'
        '400':
          $ref: '#/components/responses/BadRequest400'
        '401':
          $ref: '#/components/responses/Unauthorized401'
        '500':
          $ref: '#/components/responses/InternalServerError500'
  /authorization/logout:
    delete:
      tags:
      - TM OAuth API
      operationId: logout
      security:
      - bearerAuth: []
      summary: Logout -> gets redirected to the logout URL.
      description: 'Logout -> gets redirected to the logout URL.

        '
      responses:
        '200':
          description: OK
        '400':
          $ref: '#/components/responses/BadRequest400'
        '401':
          $ref: '#/components/responses/Unauthorized401'
        '500':
          $ref: '#/components/responses/InternalServerError500'
  /token:
    post:
      tags:
      - TM OAuth API
      operationId: refreshToken
      security:
      - bearerAuth: []
      summary: Refresh the token and retrieve a new access token, as well as a new refresh token, expiresIn and token type.
      description: 'Retrieve an access token, as well as an refresh token, expiresIn and token type.

        '
      requestBody:
        description: The request. It contains only the validation URL, if there is any
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RefreshTokenRequest'
      responses:
        '200':
          description: 'Returns an array of AuthenticationProviderData.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenResponseData'
        '400':
          $ref: '#/components/responses/BadRequest400'
        '401':
          $ref: '#/components/responses/Unauthorized401'
        '500':
          $ref: '#/components/responses/InternalServerError500'
    get:
      tags:
      - TM OAuth API
      operationId: exchangeToken
      security:
      - bearerAuth: []
      summary: Exchange an access token for/to an PCEAdminSecurityToken.
      description: 'Exchange an access token for/to an PCEAdminSecurityToken.<br>

        The PCEAdminSecurityToken is transmitted as <font color=''blue''>bases64 encoded string</font>, which was previously
        serialized <br>

        using the <font color=''blue''>PCESerializer</font>.<br>

        Therefor before you can use the PCEAdminSecurityToken in later calls, the PCEAdminSecurityToken must be decoded and
        de-serialized in the server!

        '
      parameters:
      - in: query
        name: login_reason
        required: false
        schema:
          type: string
        description: 'An optional parameter which maybe contains the login reason which is used to write an audit trails while
          login in the user.<br>

          '
      responses:
        '200':
          description: 'Returns an array of AuthenticationProviderData.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExchangeTokenResponseData'
        '400':
          $ref: '#/components/responses/BadRequest400'
        '401':
          $ref: '#/components/responses/Unauthorized401'
        '500':
          $ref: '#/components/responses/InternalServerError500'
  /test:
    get:
      tags:
      - TM OAuth API
      operationId: sandboxTest
      security:
      - basicAuth: []
      - bearerAuth: []
      summary: Endpoint to ease the tests of the API implementation.
      description: 'Test the API using a get request.<br>

        The functionality depends on the testcase.

        '
      parameters:
      - $ref: '#/components/parameters/nodeID-Param'
      - in: query
        name: testcase
        required: true
        schema:
          type: string
          enum:
          - TEST_INTERCEPTOR_RIGHTS
        description: "The name of the testcase.<br>\n<table>\n  <tr >\n    <td>Testcase name</td>\n    <td>Description</td>\n\
          \  </tr>\n\n  <tr>\n    <td>TEST_INTERCEPTOR_RIGHTS&nbsp;&nbsp;</td>\n    <td>\n      Tests if the given OAuth token\
          \ in the authorization header contains the required rights of the annotation.<br>\n      Here: IPCEAdminRights.CREATE_CUSTOMER\
          \ and IPCEAdminRights.VIEW_CUSTOMER.\n    </td>\n  </tr>\n<table>\n"
      responses:
        '200':
          description: 'Returns a http state 200 in case everything was fine.

            '
        '400':
          $ref: '#/components/responses/BadRequest400'
        '401':
          $ref: '#/components/responses/Unauthorized401'
        '500':
          $ref: '#/components/responses/InternalServerError500'
servers:
- url: http://localhost:8080/oauth-api/v1
- url: https://localhost:8080/oauth-api/v1
components:
  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
  parameters:
    nodeID-Param:
      name: nodeID
      in: header
      required: false
      description: 'The nodeID of the current node or the node the user wants to get information about.<br>

        The effective rights of the current user are checked against the effective rights of this nodeID.

        '
      schema:
        type: string
        minLength: 1
      example: '10800'
  responses:
    BadRequest400:
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized401:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound404:
      description: Not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    MethodNotAllowed405:
      description: Method Not Allowed
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    InternalServerError500:
      description: Internal Server Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    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.

            '
    AuthenticationProviderData:
      type: object
      required:
      - displayName
      - authorizationURL
      properties:
        displayName:
          type: string
          maxLength: 255
          description: 'The name of the name of the external authorization system which in human readable form, which can
            be displayed to the customer.

            '
          example: Microsoft Azure AD
        authorizationURL:
          type: string
          format: uri
          description: '''The URI is use to call the external authorization system for to authenticate the user..

            '
          example: https://login.microsoftonline.com/52846f0f-bc96-4a36-939b-f4d04bb473a0/oauth2/v2.0/authorize
    TokenResponseData:
      type: object
      required:
      - accessToken
      - tokenType
      - accessTokenExpiresIn
      - refreshToken
      - refreshTokenExpiresIn
      properties:
        accessToken:
          type: string
          description: 'The access token.<br>

            See: https://tools.ietf.org/html/rfc6750

            '
          example: eyJ0eXAiOiJKV1Q...i31s0tcsb3uI3nTMVTagD
        tokenType:
          type: string
          description: 'The access token type. Typically it''s just ''Bearer''.

            '
          example: Bearer
        accessTokenExpiresIn:
          type: integer
          description: 'Seconds until the access token is valid/duration of time the access token is granted for.

            '
          example: '3600'
        refreshToken:
          type: string
          description: 'The refresh token.

            '
          example: eyJ0eXAiOiJKV1Q...CHw16b69bOllpEdlpiALD
        refreshTokenExpiresIn:
          type: integer
          description: 'Seconds until the refresh token is valid.

            '
          example: '3600'
        scope:
          type: string
          description: 'The (optional) scope.

            '
    ExchangeTokenResponseData:
      type: object
      required:
      - pceAdminToken
      properties:
        pceAdminToken:
          type: string
          description: 'Base64 encoded PCEAdminSecurityToken.

            '
          example: c3RhdGUKaWRfdG....BhZ2UKCg==
    RefreshTokenRequest:
      type: object
      required:
      - refreshToken
      description: 'The RefreshTokenRequest.

        '
      properties:
        refreshToken:
          type: string
          description: 'The refresh token.

            '
          example: eyJhb.....ImlzcyI6Imh0dHBzOi8vaG5zaHUud2luY29yLW5peGRvcmYuY2
    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
    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
    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'