From 3d2885f2b8f1bd45c43111db8062d9afdd4d17df Mon Sep 17 00:00:00 2001 From: "b.boterman@htm.nl" Date: Thu, 18 Jun 2026 14:43:08 +0200 Subject: [PATCH] OVPAY-2485 - Added support for anonymous TAT security. --- src/openapi/customers/SE-customers-v2.yaml | 339 -------------------- src/openapi/customers/SE-tat-security.yaml | 341 +++++++++++++++++++++ 2 files changed, 341 insertions(+), 339 deletions(-) create mode 100644 src/openapi/customers/SE-tat-security.yaml diff --git a/src/openapi/customers/SE-customers-v2.yaml b/src/openapi/customers/SE-customers-v2.yaml index 8710a1e..29fd300 100644 --- a/src/openapi/customers/SE-customers-v2.yaml +++ b/src/openapi/customers/SE-customers-v2.yaml @@ -3776,240 +3776,6 @@ paths: responses: "200": description: OK - /customers/tokens/{ovPayTokenId}/activateago: - parameters: - - name: ovPayTokenId - in: path - required: true - style: simple - description: Id of the OvPayToken to activate AGO for. - schema: - type: integer - example: 1 - - name: X-HTM-JWT-AUTH-HEADER - in: header - schema: - type: string - example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c - required: false - description: The JWT of a customer in case of touchpoint were customer logs in themselves - - name: X-HTM-CUSTOMER-PROFILE-ID-HEADER - in: header - schema: - type: integer - example: 323 - required: false - description: The id of the customer Profile - - name: X-HTM-ROLE-HEADER - in: header - schema: - type: string - example: Customer - required: false - description: The role of the HTM employee in the case of the SMP - post: - tags: - - AGO - summary: Request additional OV-pas security for a token in profile. - description: Request additional OV-pas security for a token in profile. - requestBody: - content: - application/json: - schema: - $ref: "#/components/schemas/ActivateAgoRequest" - example: - emailAddress: stasjo@htm.nl - responses: - "200": - description: OK - content: - application/json: - schema: - oneOf: - - $ref: "#/components/schemas/EmailPreApprovedResponse" - - $ref: "#/components/schemas/EmailNotPreApprovedResponse" - examples: - Email preapproved: - value: - status: Success - description: TAT Secured - Email not preapproved: - value: - uid: 7594f3ee-cd3d-40a3-8e82-73b90d16c481 - recipient: xxxxxx.user@gmail.com - key: 123456789123456789123456789abcde - description: OTP Sent - "400": - description: Bad Request - content: - application/json: - schema: - $ref: "#/components/schemas/ErrorResponse" - examples: - Missing Parameters: - value: - status: 400 - title: Missing Mandatory Parameter - detail: Required parameter {0} is missing. - Invalid Parameters: - value: - status: 400 - title: Invalid Parameter - detail: Required parameter {0} is invalid. - "401": - description: Unauthorized - content: - application/json: - schema: - $ref: "#/components/schemas/ErrorResponse" - examples: - Unauthorized: - value: - status: 401 - title: Unauthorized - detail: Invalid Access Token - "404": - description: Not found - content: - application/json: - schema: - $ref: "#/components/schemas/ErrorResponse" - examples: - TAT not found: - value: - status: 404 - title: Not Found - detail: TAT Account Not Found - "409": - description: Conflict - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorResponse' - examples: - TAT Already Secured: - value: - status: 409 - title: Conflict - detail: TAT Already Secured - "500": - description: Internal server error - content: - application/json: - schema: - $ref: "#/components/schemas/ErrorResponse" - example: - error: An unknown error has occurred - /customers/tokens/{ovPayTokenId}/validateotp: - parameters: - - name: ovPayTokenId - in: path - required: true - style: simple - description: Id of the OvPayToken to verify OTP for. - schema: - type: integer - example: 1 - - name: X-HTM-JWT-AUTH-HEADER - in: header - schema: - type: string - example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c - required: false - description: The JWT of a customer in case of touchpoint were customer logs in themselves - - name: X-HTM-CUSTOMER-PROFILE-ID-HEADER - in: header - schema: - type: integer - example: 323 - required: false - description: The id of the customer Profile - - name: X-HTM-ROLE-HEADER - in: header - schema: - type: string - example: Customer - required: false - description: The role of the HTM employee in the case of the SMP - post: - tags: - - AGO - summary: Submit an OTP for a triggered OTP flow. - description: | - Submit an OTP for a triggered OTP flow. This can either be result of an AGO activation, or - result of an AGO authorization flow. Since the backoffice behaves slightly different depending - on which use case is executed, the calling TP needs to provide an `action` in the request body. - requestBody: - content: - application/json: - schema: - $ref: "#/components/schemas/VerifyOtpRequest" - examples: - OTP verification for TAT security activation: - value: - otp: 123456 - action: secure - OTP verification for TAT security authorization: - value: - otp: 123456 - action: authorize - responses: - "200": - description: OK - content: - application/json: - schema: - $ref: '#/components/schemas/VerifyOtpResponse' - examples: - Tat Secured: - value: - status: Success - description: TAT Secured - Tat Unsecured: - value: - status: Success - description: TAT Unsecured - Tat Authorized: - value: - status: Success - description: TAT Authorized - "400": - description: Bad request - content: - application/json: - schema: - $ref: "#/components/schemas/ErrorResponse" - examples: - Missing Parameters: - value: - status: 400 - title: Missing Mandatory Parameter - detail: Required parameter {0} is missing. - Invalid Parameters: - value: - status: 400 - title: Invalid Parameter - detail: Required parameter {0} is invalid. - "401": - description: Unauthorized - content: - application/json: - schema: - $ref: "#/components/schemas/ErrorResponse" - examples: - Unauthorized: - value: - status: 401 - title: Unauthorized - detail: Invalid Access Token - "500": - description: Internal server error - content: - application/json: - schema: - $ref: "#/components/schemas/ErrorResponse" - example: - error: An unknown error has occurred components: schemas: unavailable: @@ -4896,108 +4662,3 @@ components: customerDataItem: type: string example: emailAddress - GenerateTatOutput: - type: object - properties: - uid: - type: string - description: >- - An uid IS A unique identifier THAT is associated with the - user. - recipient: - type: string - description: >- - A recipient IS A unique identifier THAT is associated with the - TAT owner. - key: - type: string - description: >- - A key IS a 32 character string THAT uniquely identifies the - OTP session. - EmailPreApprovedResponse: - type: object - description: >- - AN EmailPreApprovedResponse IS AN object THAT represents the response of - email pre-approval check. - properties: - status: - type: string - description: >- - A status IS A boolean THAT indicates that the provided email address - is pre-approved by the calling client app/web. - example: Success - description: - type: string - description: >- - A description IS A string THAT provides additional information - relating to the aprroval result - example: TAT Secured - EmailNotPreApprovedResponse: - type: object - description: >- - EmailNotPreApprovedResponse IS AN object THAT represents the response of - email pre-approval check. - properties: - uid: - type: string - description: A uid IS A unique identifier THAT is associated with the user. - example: 7594f3ee-cd3d-40a3-8e82-73b90d16c481 - recipient: - type: string - description: >- - A recipient IS A unique identifier THAT is associated with the TAT - owner. - example: xxxxxx.user@gmail.com - key: - type: string - description: >- - A key IS a 32 character string THAT uniquely identifies the OTP - session. - example: 123456789123456789123456789abcde - description: - type: string - description: >- - A description IS A string THAT describes the reason why the email is - not pre-approved. - example: OTP Sent - ActivateAgoRequest: - type: object - properties: - emailAddress: - type: string - format: email - example: stasjo@htm.nl - VerifyOtpRequest: - type: object - properties: - emailAddress: - type: string - example: 123456 - action: - type: string - example: secure - VerifyOtpResponse: - type: object - properties: - status: - type: string - example: Success - description: - type: string - example: TAT Secured - ErrorResponse: - description: Default response when an invalid request has been sent - type: object - properties: - status: - type: integer - description: >- - A status IS An integer that represents the HTTP status code of the - response. - example: 400 - title: - type: string - description: A title IS A string that provides a brief summary of the error. - detail: - type: string - description: A detail IS A string that provides more details about the error. \ No newline at end of file diff --git a/src/openapi/customers/SE-tat-security.yaml b/src/openapi/customers/SE-tat-security.yaml new file mode 100644 index 0000000..1cb6920 --- /dev/null +++ b/src/openapi/customers/SE-tat-security.yaml @@ -0,0 +1,341 @@ +openapi: 3.0.1 +info: + title: Service Engine APIs for TAT security + description: >- + Service Engine APIs for TAT security. These are NOT the raw GBO APIs to access TAT security at GBO directly. + To be used by touch points to get secure a TAT. + version: "2.0" +servers: + - url: https://services.acc.api.htm.nl/abt/touchpoint/2.0 +tags: + - name: TAT Security +paths: + /tokens/securetoken: + parameters: + - name: X-HTM-JWT-AUTH-HEADER + in: header + schema: + type: string + example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c + required: false + description: The JWT of a customer in case of touchpoint were customer logs in themselves + - name: X-HTM-CUSTOMER-PROFILE-ID-HEADER + in: header + schema: + type: integer + example: 323 + required: false + description: The id of the customer Profile + - name: X-HTM-ROLE-HEADER + in: header + schema: + type: string + example: Customer + required: false + description: The role of the HTM employee in the case of the SMP + post: + tags: + - TAT Security + summary: Request additional OV-pas security for a token either in profile or anonymous. + description: Request additional OV-pas security for a token either in profile or anonymous + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/SecureTokenRequest" + examples: + With customer account: + value: + ovPayTokenId: 42 + emailAddress: stasjo@htm.nl + Without customer account: + value: + xtat: 62914b49-2c7f-437f-b4b0-2ad61a9f902d + emailAddress: stasjo@htm.nl + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: "#/components/schemas/EmailNotPreApprovedResponse" + example: + uid: 7594f3ee-cd3d-40a3-8e82-73b90d16c481 + recipient: xxxxxx.user@gmail.com + key: 123456789123456789123456789abcde + description: OTP Sent + "400": + description: Bad Request + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorResponse" + examples: + Missing Parameters: + value: + status: 400 + title: Missing Mandatory Parameter + detail: Required parameter {0} is missing. + Invalid Parameters: + value: + status: 400 + title: Invalid Parameter + detail: Required parameter {0} is invalid. + "401": + description: Unauthorized + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorResponse" + examples: + Unauthorized: + value: + status: 401 + title: Unauthorized + detail: Invalid Access Token + "404": + description: Not found + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorResponse" + examples: + TAT not found: + value: + status: 404 + title: Not Found + detail: TAT Account Not Found + "409": + description: Conflict + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorResponse' + examples: + TAT Already Secured: + value: + status: 409 + title: Conflict + detail: TAT Already Secured + "500": + description: Internal server error + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorResponse" + example: + error: An unknown error has occurred + /customers/verifyotp: + parameters: + - name: X-HTM-JWT-AUTH-HEADER + in: header + schema: + type: string + example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c + required: false + description: The JWT of a customer in case of touchpoint were customer logs in themselves + - name: X-HTM-CUSTOMER-PROFILE-ID-HEADER + in: header + schema: + type: integer + example: 323 + required: false + description: The id of the customer Profile + - name: X-HTM-ROLE-HEADER + in: header + schema: + type: string + example: Customer + required: false + description: The role of the HTM employee in the case of the SMP + post: + tags: + - TAT Security + summary: Submit an OTP for a triggered OTP flow. + description: | + Submit an OTP for a triggered OTP flow. This can either be result of an AGO activation, or + result of an AGO authorization flow. Since the backoffice behaves slightly different depending + on which use case is executed, the calling TP needs to provide an `action` in the request body. + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/VerifyOtpRequest" + examples: + OTP verification for TAT security activation for token in customer account: + value: + ovPayTokenId: 42 + otp: 123456 + action: secure + OTP verification for TAT security authorization for anonymous token: + value: + xtat: 0f0defe8-828c-48e5-97e5-26d1d0179ef0 + otp: 123456 + action: authorize + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/VerifyOtpResponse' + examples: + Tat Secured: + value: + status: Success + description: TAT Secured + Tat Unsecured: + value: + status: Success + description: TAT Unsecured + Tat Authorized: + value: + status: Success + description: TAT Authorized + "400": + description: Bad request + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorResponse" + examples: + Missing Parameters: + value: + status: 400 + title: Missing Mandatory Parameter + detail: Required parameter {0} is missing. + Invalid Parameters: + value: + status: 400 + title: Invalid Parameter + detail: Required parameter {0} is invalid. + "401": + description: Unauthorized + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorResponse" + examples: + Unauthorized: + value: + status: 401 + title: Unauthorized + detail: Invalid Access Token + "500": + description: Internal server error + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorResponse" + example: + error: An unknown error has occurred +components: + schemas: + unavailable: + type: object + GenerateTatOutput: + type: object + properties: + uid: + type: string + description: >- + An uid IS A unique identifier THAT is associated with the + user. + recipient: + type: string + description: >- + A recipient IS A unique identifier THAT is associated with the + TAT owner. + key: + type: string + description: >- + A key IS a 32 character string THAT uniquely identifies the + OTP session. + EmailNotPreApprovedResponse: + type: object + description: >- + EmailNotPreApprovedResponse IS AN object THAT represents the response of + email pre-approval check. + properties: + uid: + type: string + description: A uid IS A unique identifier THAT is associated with the user. + example: 7594f3ee-cd3d-40a3-8e82-73b90d16c481 + recipient: + type: string + description: >- + A recipient IS A unique identifier THAT is associated with the TAT + owner. + example: xxxxxx.user@gmail.com + key: + type: string + description: >- + A key IS a 32 character string THAT uniquely identifies the OTP + session. + example: 123456789123456789123456789abcde + description: + type: string + description: >- + A description IS A string THAT describes the reason why the email is + not pre-approved. + example: OTP Sent + SecureTokenRequest: + type: object + properties: + ovPayTokenId: + type: integer + example: 42 + xtat: + type: string + format: uuid + example: 6134db53-9ae5-41d1-a343-36656b60b510 + emailAddress: + type: string + format: email + example: stasjo@htm.nl + required: + - ovPayTokenId + VerifyOtpRequest: + type: object + properties: + ovPayTokenId: + type: integer + example: 42 + xtat: + type: string + format: uuid + example: f3474452-e1d4-428c-b366-e5ad5965eb8c + otp: + type: string + example: 123456 + action: + type: string + example: secure + required: + - otp + - action + VerifyOtpResponse: + type: object + properties: + status: + type: string + example: Success + description: + type: string + example: TAT Secured + ErrorResponse: + description: Default response when an invalid request has been sent + type: object + properties: + status: + type: integer + description: >- + A status IS An integer that represents the HTTP status code of the + response. + example: 400 + title: + type: string + description: A title IS A string that provides a brief summary of the error. + detail: + type: string + description: A detail IS A string that provides more details about the error. \ No newline at end of file