added authorize endpoint and get securitystatus endpoint

This commit is contained in:
Mirjam Herald 2026-07-28 14:15:18 +02:00
parent 23dd83fac9
commit 5b3264d9cd
2 changed files with 433 additions and 15 deletions

View File

@ -10,6 +10,150 @@ servers:
tags: tags:
- name: TAT Security - name: TAT Security
paths: paths:
/tokens/status:
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
- name: xTat
in: query
schema:
type: string
format : uuid
example: 5c4cba83-1ecd-46a4-b712-a8de0dcb7bbf
required: false
description: The xtat of the customerToken
- name: ovPayTokenId
in: query
schema:
type: integer
example: 1
required: false
description: The ovpay token id of a specific customer token
- name: serviceReferenceId
in: query
schema:
type: string
example: NLOV1234567ABCDEFG
required: false
description: The serviceReferencId found on the bankstatement for a given trip with a bankcard, required for an unknown EMV card
- name: amount
in: query
schema:
type: integer
example: 0
required: false
description: The amount of the value of the bankstatement in cents, required for an unknown EMV card
- name: ovpasNumber
in: query
schema:
type: string
example: OV34567
required: false
description: The number of the ovpas, required for an unknown Ovpas card
- name: verificationCode
in: query
schema:
type: string
example: HL78
required: false
description: The 4 digit verificationCode found on the backside of the Ovpas, required for an unknown Ovpas card
get:
tags:
- TAT Security
summary: Check the status of the security and authorization status of the given token
description: Check the status of the security and authorization status of the given token, check anonymous tokenDB if no customer headers are supplied otherwise check customer tokenDB
responses:
"200":
description: OK
content:
application/json:
schema:
$ref: "#/components/schemas/TokenStatusResponse"
example:
isSecured: true
isAuthorized: false
xTat: 12da8f2a-6390-408a-94eb-a6701b5daf27
"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
/tokens/securetoken: /tokens/securetoken:
parameters: parameters:
- name: X-HTM-JWT-AUTH-HEADER - name: X-HTM-JWT-AUTH-HEADER
@ -60,9 +204,7 @@ paths:
schema: schema:
$ref: "#/components/schemas/EmailNotPreApprovedResponse" $ref: "#/components/schemas/EmailNotPreApprovedResponse"
example: example:
uid: 7594f3ee-cd3d-40a3-8e82-73b90d16c481
recipient: xxxxxx.user@gmail.com recipient: xxxxxx.user@gmail.com
key: 123456789123456789123456789abcde
description: OTP Sent description: OTP Sent
"400": "400":
description: Bad Request description: Bad Request
@ -125,6 +267,105 @@ paths:
$ref: "#/components/schemas/ErrorResponse" $ref: "#/components/schemas/ErrorResponse"
example: example:
error: An unknown error has occurred error: An unknown error has occurred
/tokens/authorizetoken:
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 Authorization
summary: Request authorization for HTM to access the data secured by additional OV-pas security for a token either in profile or anonymous.
description: Request authorization for HTM to access the data secured by additional OV-pas security for a token either in profile or anonymous.
requestBody:
content:
application/json:
schema:
$ref: "#/components/schemas/AuthorizeTokenRequest"
examples:
With customer account:
value:
ovPayTokenId: 42
Without customer account:
value:
xtat: 62914b49-2c7f-437f-b4b0-2ad61a9f902d
responses:
"200":
description: OK
content:
application/json:
schema:
$ref: "#/components/schemas/EmailNotPreApprovedResponse"
example:
recipient: xxxxxx.user@gmail.com
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
"500":
description: Internal server error
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
example:
error: An unknown error has occurred
/tokens/verifyotp: /tokens/verifyotp:
parameters: parameters:
- name: X-HTM-JWT-AUTH-HEADER - name: X-HTM-JWT-AUTH-HEADER
@ -150,7 +391,7 @@ paths:
description: The role of the HTM employee in the case of the SMP description: The role of the HTM employee in the case of the SMP
post: post:
tags: tags:
- TAT Security - TAT Verification
summary: Submit an OTP for a triggered OTP flow. summary: Submit an OTP for a triggered OTP flow.
description: | description: |
Submit an OTP for a triggered OTP flow. This can either be result of an AGO activation, or Submit an OTP for a triggered OTP flow. This can either be result of an AGO activation, or
@ -257,22 +498,12 @@ components:
EmailNotPreApprovedResponse IS AN object THAT represents the response of EmailNotPreApprovedResponse IS AN object THAT represents the response of
email pre-approval check. email pre-approval check.
properties: properties:
uid:
type: string
description: A uid IS A unique identifier THAT is associated with the user.
example: 7594f3ee-cd3d-40a3-8e82-73b90d16c481
recipient: recipient:
type: string type: string
description: >- description: >-
A recipient IS A unique identifier THAT is associated with the TAT A recipient IS A unique identifier THAT is associated with the TAT
owner. owner.
example: xxxxxx.user@gmail.com 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: description:
type: string type: string
description: >- description: >-
@ -294,7 +525,17 @@ components:
format: email format: email
example: stasjo@htm.nl example: stasjo@htm.nl
required: required:
- ovPayTokenId - emailAddress
AuthorizeTokenRequest:
type: object
properties:
ovPayTokenId:
type: integer
example: 42
xtat:
type: string
format: uuid
example: 6134db53-9ae5-41d1-a343-36656b60b510
VerifyOtpRequest: VerifyOtpRequest:
type: object type: object
properties: properties:
@ -338,4 +579,30 @@ components:
description: A title IS A string that provides a brief summary of the error. description: A title IS A string that provides a brief summary of the error.
detail: detail:
type: string type: string
description: A detail IS A string that provides more details about the error. description: A detail IS A string that provides more details about the error.
TokenStatusResponse:
type: object
description: >-
TokenStatusResponse IS AN object THAT represents the current state of the token in relation to the AGO security and authorization status of HTM.
required:
- isSecured
- isAuthorized
- xTat
properties:
isSecured:
type: boolean
description: >-
Is the token secured in the national database (GBO)
example: false
isAuthorized:
type: boolean
description: >-
Does HTM have the authorization to access the secured data for this token, only applicable when isSecured equals True.
example: false
xTat:
type: string
format: uuid
description: >-
The xtat of the customerToken
example: 883674e5-54c7-47d6-a3e3-8781f0d3ffea

151
trip2.json Normal file
View File

@ -0,0 +1,151 @@
{ "tripId": 796727186, "tripVersion": 1, "tripStatus": "COMPLETE", "organisationIcon": "/icons/organisations/3.svg", "organisationId": "3", "organisationName": "HTM", "supersededByTripIds": [], "supersedesTripIds": [], "products": [ {
"productTemplateId": "30901", "productCommercialName": { "items": [ {
"key": "nl-NL", "value": "HTM 90% Korting" },
{
"key": "en-US", "value": "HTM 90% Discount" }
]
},
"productIcon": "001.jpg", "purchaseDateTime": "2026-04-02T12:38:28+02:00", "organisationName": "ProductRetailer HTM", "appliedValue": -125, "organisationId": "3", "category": "SALES", "typesOfFareProduct": [ {
"privateCode": "discount" }
],
"xspit": "821ddb0d-4ea7-4a0d-84aa-bb7facce15d1" },
{
"productTemplateId": "N/A", "purchaseDateTime": "2025-07-09T12:39:27+02:00", "appliedValue": 139, "category": "SALES", "typesOfFareProduct": [ {
"privateCode": "payg" }
],
"xspit": "7618337f-c986-4bef-990d-f5a6b47292b8" },
{
"productTemplateId": "1:2000", "productCommercialName": { "items": [ {
"key": "nl-NL", "value": "Basis Bus Tram Metro" },
{
"key": "en-US", "value": "BTM full fare" }
]
},
"validFrom": "2000-01-01T01:00:00+01:00", "validUntil": "2100-01-01T00:59:59+01:00", "weight": 116, "appliedMetric": "FARE", "appliedValue": 116, "category": "INTERNAL", "typesOfFareProduct": [ {
"privateCode": "payg" }
],
"xspit": "7618337f-c986-4bef-990d-f5a6b47292b8", "xpit": "f4256df6-b767-460f-9880-f7597bd7f3f2" },
{
"productTemplateId": "2:2000", "productCommercialName": { "items": [ {
"key": "nl-NL", "value": "Basis Bus Tram Metro" },
{
"key": "en-US", "value": "BTM full fare" }
]
},
"validFrom": "2000-01-01T01:00:00+01:00", "validUntil": "2100-01-01T00:59:59+01:00", "weight": 23, "appliedMetric": "FARE", "appliedValue": 23, "category": "INTERNAL", "typesOfFareProduct": [ {
"privateCode": "payg" }
],
"xspit": "7618337f-c986-4bef-990d-f5a6b47292b8", "xpit": "f4256df6-b767-460f-9880-f7597bd7f3f2" },
{
"productTemplateId": "3:30901", "productCommercialName": { "items": [ {
"key": "nl-NL", "value": "HTM 90% Korting" },
{
"key": "en-US", "value": "HTM 90% Discount" },
{
"key": "nl-NL", "value": "Reis je regelmatig met HTM? Activeer dan HTM 90% Korting op je betaalpas of credit card en reis een week lang met korting!" },
{
"key": "en-US", "value": "Are you a regular traveler? Activate HTM 90% discount on your EMV card!" }
]
},
"validFrom": "2026-04-03T04:00:00+02:00", "validUntil": "2031-04-03T04:00:00+02:00", "organisationName": "Product Owner HTM", "weight": -125, "appliedMetric": "DISCOUNT", "appliedValue": -125, "organisationId": "3", "category": "INTERNAL", "typesOfFareProduct": [ {
"privateCode": "discount" }
],
"productCatalogVersionId": "PC-HTM:70", "xspit": "821ddb0d-4ea7-4a0d-84aa-bb7facce15d1", "xpit": "1848597c-5ba9-4dab-8d9f-3948948706a1" }
],
"checkinTransactionTimestamp": "2026-04-20T16:59:48+02:00", "checkoutTransactionTimestamp": "2026-04-20T17:04:50+02:00", "checkinTransactionReference": "00310F92;29023;emvClt", "checkoutTransactionReference": "0030DBC1;30528;emvClt", "checkinLocation": { "stopId": 2721, "stopName": { "items": [ {
"key": "nl-NL", "value": "Station Hollands Spoor" },
{
"key": "en-US", "value": "Station Hollands Spoor" }
]
},
"stopDesc": "Stop point2721", "stopUrl": "/icons/stops/stop.svg", "locationType": 0 },
"checkoutLocation": { "stopId": 2862, "stopName": { "items": [ {
"key": "nl-NL", "value": "Kalvermarkt-Stadhuis" },
{
"key": "en-US", "value": "Kalvermarkt-Stadhuis" }
]
},
"stopDesc": "Stop point2862", "stopUrl": "/icons/stops/stop.svg", "locationType": 0 },
"tokenType": "EMV-CLT", "transportType": "TRAM", "lineId": "17", "lineName": "Tram17", "networkId": "1", "networkName": "HTM netwerk", "currency": "EUR", "transportIcon": "/icons/transportTypes/tram.svg", "legs": [ {
"legId": 1614950977, "checkinTransactionTimestamp": "2026-04-20T16:59:48+02:00", "checkoutTransactionTimestamp": "2026-04-20T17:04:50+02:00", "checkinLocation": { "stopId": 2721, "stopName": { "items": [ {
"key": "nl-NL", "value": "Station Hollands Spoor" },
{
"key": "en-US", "value": "Station Hollands Spoor" }
]
},
"stopDesc": "Stop point2721", "stopUrl": "/icons/stops/stop.svg", "locationType": 0 },
"checkoutLocation": { "stopId": 2862, "stopName": { "items": [ {
"key": "nl-NL", "value": "Kalvermarkt-Stadhuis" },
{
"key": "en-US", "value": "Kalvermarkt-Stadhuis" }
]
},
"stopDesc": "Stop point2862", "stopUrl": "/icons/stops/stop.svg", "locationType": 0 },
"baseRate": 139, "lineId": "17", "lineName": "Tram17", "networkId": "1", "networkName": "HTM netwerk", "fare": 14, "fareState": "CALCULATED", "currency": "EUR", "products": [ {
"productTemplateId": "30901", "productCommercialName": { "items": [ {
"key": "nl-NL", "value": "HTM 90% Korting" },
{
"key": "en-US", "value": "HTM 90% Discount" }
]
},
"productIcon": "001.jpg", "purchaseDateTime": "2026-04-02T12:38:28+02:00", "organisationName": "ProductRetailer HTM", "appliedValue": -125, "organisationId": "3", "category": "SALES", "typesOfFareProduct": [ {
"privateCode": "discount" }
],
"xspit": "821ddb0d-4ea7-4a0d-84aa-bb7facce15d1" },
{
"productTemplateId": "N/A", "purchaseDateTime": "2025-07-09T12:39:27+02:00", "appliedValue": 139, "category": "SALES", "typesOfFareProduct": [ {
"privateCode": "payg" }
],
"xspit": "7618337f-c986-4bef-990d-f5a6b47292b8" },
{
"productTemplateId": "1:2000", "productCommercialName": { "items": [ {
"key": "nl-NL", "value": "Basis Bus Tram Metro" },
{
"key": "en-US", "value": "BTM full fare" }
]
},
"validFrom": "2000-01-01T01:00:00+01:00", "validUntil": "2100-01-01T00:59:59+01:00", "weight": 116, "appliedMetric": "FARE", "appliedValue": 116, "category": "INTERNAL", "typesOfFareProduct": [ {
"privateCode": "payg" }
],
"xspit": "7618337f-c986-4bef-990d-f5a6b47292b8", "xpit": "f4256df6-b767-460f-9880-f7597bd7f3f2" },
{
"productTemplateId": "2:2000", "productCommercialName": { "items": [ {
"key": "nl-NL", "value": "Basis Bus Tram Metro" },
{
"key": "en-US", "value": "BTM full fare" }
]
},
"validFrom": "2000-01-01T01:00:00+01:00", "validUntil": "2100-01-01T00:59:59+01:00", "weight": 23, "appliedMetric": "FARE", "appliedValue": 23, "category": "INTERNAL", "typesOfFareProduct": [ {
"privateCode": "payg" }
],
"xspit": "7618337f-c986-4bef-990d-f5a6b47292b8", "xpit": "f4256df6-b767-460f-9880-f7597bd7f3f2" },
{
"productTemplateId": "3:30901", "productCommercialName": { "items": [ {
"key": "nl-NL", "value": "HTM 90% Korting" },
{
"key": "en-US", "value": "HTM 90% Discount" },
{
"key": "nl-NL", "value": "Reis je regelmatig met HTM? Activeer dan HTM 90% Korting op je betaalpas of credit card en reis een week lang met korting!" },
{
"key": "en-US", "value": "Are you a regular traveler? Activate HTM 90% discount on your EMV card!" }
]
},
"validFrom": "2026-04-03T04:00:00+02:00", "validUntil": "2031-04-03T04:00:00+02:00", "organisationName": "Product Owner HTM", "weight": -125, "appliedMetric": "DISCOUNT", "appliedValue": -125, "organisationId": "3", "category": "INTERNAL", "typesOfFareProduct": [ {
"privateCode": "discount" }
],
"discountPercentage": 90, "productCatalogVersionId": "PC-HTM:70", "xspit": "821ddb0d-4ea7-4a0d-84aa-bb7facce15d1", "xpit": "1848597c-5ba9-4dab-8d9f-3948948706a1" }
],
"appliedTimePeriods": [], "tariffJourneyStart": true, "topoDistance": 1161, "concessionId": "1", "appliedZones": [] }
],
"lastUpdatedTripDateTime": "2026-04-20T17:04:50+02:00", "fare": 14, "loyaltyOrDiscount": true, "supportCode": "pWM8Km6J8aHg5n", "tripVersionReason": "STRUCTURE", "checkinTransactionId": "00310F92-29023-emvClt-1776697188000", "checkoutTransactionId": "0030DBC1-30528-emvClt-1776697490000", "tariffVersionId": "HTM-CF1:278", "correlationId": "4bc7a040-71bf-4084-a61e-b2dd72092079", "createdAt": "2026-04-20T17:05:01.473+02:00", "entryTariffLocation": { "stopId": 2721, "stopName": { "items": [ {
"key": "nl-NL", "value": "Station Hollands Spoor" },
{
"key": "en-US", "value": "Station Hollands Spoor" }
]
},
"stopDesc": "Stop point2721", "stopUrl": "/icons/stops/stop.svg", "locationType": 0 },
"traveledLines": [ {
"lineId": "17", "lineName": "Tram17" }
],
"tripFareNature": "FIXED", "paymentMethodId": "229a01ff-7bd9-4740-9b19-00637146a6ca", "paymentMethodMode": "PREPAID", "paymentMethodName": "EPURSE", "paymentProviderName": "TPURSE", "paymentProviderBusinessEntityId": "600027", "registryFragmentVersionId": "REG:27", "vehicleId": 5063, "xbot": "c85e34d6-f9c1-49c2-8574-59b37e0f3b8e" }