{"openapi":"3.0.3","info":{"title":"DN TM Authorization API","description":"Public TM Authorization API of Diebold Nixdorf to access the Transaction Middleware.\n","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.\n","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\n","description":"An endpoint to authenticates an user and returns on success a JWT token for all further requests.<br>\nThe access token is valid for 1 hour, if not set to a different value in the TM configuration.<br>\nThe user will be logged in and his initial hierarchy will be loaded.<br>\n<font color='red'><b>ATTENTION:</b></font><br>\nThe delivered access token has to be used in the <b><l>Authorization</l></b> header attribute of all further requests.<br>\nMoreover, 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>\nPlease see: $ref: '#/components/parameters/nodeID-Param'<br>\nMoreover, together with the access token some other information are returned in the response such as the root node hierarchy, granted rights etc..<br>\n","operationId":"tm-authenticate","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TmAuthenticationRequest"}}}},"responses":{"200":{"description":"Th user has been authenticated.\n","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.\n","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.\n","description":"An endpoint to get the public keys to verify the JWT token.\n","operationId":"tm-get-keys","responses":{"200":{"description":"Th user has been authenticated.\n","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>\nThe 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>\nThis parameter will be added to the <b><l>redirect_url</b></l> as an \"application/x-www-form-urlencoded\" formatted query component.\n"},{"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.\n","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>\n<font color='red'><b>Do NOT call this endpoint directly</b></font>, because it's called by the authorization server via http 302 redirect.\n","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>\n<br>\nAt this point, the user is already logged in and their original hierarchy has been loaded.<br>\n<font color='red'><b>ATTENTION:</b></font><br>\nThe delivered access token has to be used in the <b><l>Authorization</l></b> header attribute <b>of all further requests</b>.<br>\nMoreover, 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>\nPlease see: $ref: '#/components/parameters/nodeID-Param'\n","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.\n","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.\n","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.\n","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>\nThe PCEAdminSecurityToken is transmitted as <font color='blue'>bases64 encoded string</font>, which was previously serialized <br>\nusing the <font color='blue'>PCESerializer</font>.<br>\nTherefor before you can use the PCEAdminSecurityToken in later calls, the PCEAdminSecurityToken must be decoded and de-serialized in the server!\n","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>\n"}],"responses":{"200":{"description":"Returns an array of AuthenticationProviderData.\n","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>\nThe functionality depends on the testcase.\n","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.\n"},"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.\n","scheme":"basic"},"bearerAuth":{"type":"http","description":"When using the bearer authentication method an access token has to be provided in the HTTP authorization header\n","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>\nThe effective rights of the current user are checked against the effective rights of this nodeID.\n","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.\n","required":["rightId","rightName"],"properties":{"rightId":{"type":"string","description":"The id of the right.\n"},"rightName":{"type":"string","description":"The right in a human readable form.\n"},"rightDescription":{"type":"string","description":"The description of the right in a human readable form.\n"}}},"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.\n","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..\n","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>\nSee: https://tools.ietf.org/html/rfc6750\n","example":"eyJ0eXAiOiJKV1Q...i31s0tcsb3uI3nTMVTagD"},"tokenType":{"type":"string","description":"The access token type. Typically it's just 'Bearer'.\n","example":"Bearer"},"accessTokenExpiresIn":{"type":"integer","description":"Seconds until the access token is valid/duration of time the access token is granted for.\n","example":"3600"},"refreshToken":{"type":"string","description":"The refresh token.\n","example":"eyJ0eXAiOiJKV1Q...CHw16b69bOllpEdlpiALD"},"refreshTokenExpiresIn":{"type":"integer","description":"Seconds until the refresh token is valid.\n","example":"3600"},"scope":{"type":"string","description":"The (optional) scope.\n"}}},"ExchangeTokenResponseData":{"type":"object","required":["pceAdminToken"],"properties":{"pceAdminToken":{"type":"string","description":"Base64 encoded PCEAdminSecurityToken.\n","example":"c3RhdGUKaWRfdG....BhZ2UKCg=="}}},"RefreshTokenRequest":{"type":"object","required":["refreshToken"],"description":"The RefreshTokenRequest.\n","properties":{"refreshToken":{"type":"string","description":"The refresh token.\n","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\nES256 for Elliptic Curve using P-256 and SHA-256.\n","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.\n","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.\n","example":"de"},"timezone":{"type":"string","format":"tz database","description":"set the timezone for this session.\n","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.\n","example":"DE"}}},"TmAuthenticationResponse":{"type":"object","description":"Describes the response of the authentication request.\n","required":["state","message"],"properties":{"status":{"type":"string","enum":["OK","FAILED"]},"message":{"type":"string","description":"Description of what went wrong.\n"},"jwt":{"type":"string","format":"JSON Web Token","description":"After successful authentication a JSON Web Token is returned for further requests\n"},"userName":{"type":"string","description":"The display name of the current user.\n"},"userLocale":{"type":"string","description":"The locale of the current user.\n"},"userTimeZone":{"type":"string","description":"The timezone name of the current user.\n"},"rootNodeIDs":{"type":"array","items":{"type":"string","description":"The root node IDs of the current user.\n"}},"rootNodeType":{"type":"string","description":"The type of the root node of the user's hierarchy.\n"},"rights":{"description":"The rights list of the current user.\n","type":"array","items":{"$ref":"#/components/schemas/TmRight"}}}}}}}