Version: 1.8

Updated at: 2025-04-01

Introduction

Samtrafiken provides an access point enabling third party retailers to fetch products and tickets from ticket issuing BoB Participants, such as PTAs. For more information on the BoB standard, please visit BoB - National Ticket & Payment Standards for Public Transport ¹.

This guide aims to describe the APIs Samtrafiken makes available, and an introduction on how to use them. It is assumed that readers of this guide have some basic knowledge of BoB concepts.

APIs

The following APIs enable retailers to fetch and manage BoB tickets from ticket issuers:

• Samtrafiken Device Management API - allows retailers to fetch the Device IDs and Device Keys required to add the Device Signature (adding copy protection) to an MTB

• Samtrafiken Connect API - allows retailers to fetch products and tickets from ticket issuers

Please note that neither of these are standard BoB APIs. The BoB APIs are designed for one-to-one integrations, eg. for a retailer to fetch BoB Products from a ticket issuer using a certain version of the BoB Product API. Samtrafiken Connect API and Samtrafiken Device Management API however are proprietary APIs enabling:

• A BoB version independent way of performing certain BoB operations towards connected ticket issuers:

  • Retrieve ticket issuers' traveller categories and product categories

  • Retrieve BoB Products

  • Retrieve BoB Tickets

  • Refund BoB Tickets

  • Revoke BoB Tickets

• Device ID and Device Key creation

• Authentication using Auth2/OpenID Connect

  • For detailed information about authentication processes, refer to the Samtrafiken Authentication Guide. This guide provides comprehensive instructions on implementing OAuth2 and OpenID Connect for secure access.

The APIs are documented using the Open API 3 specification format.

The APIs are not BoB APIs, but they share concepts and terminology with the BoB APIs, in order to ease understanding and compatibility for retailers that have already invested in BoB.

Device Management API

Samtrafiken Device Management API enables retailers to conveniently create Device IDs and Device Keys. Device IDs and Device Keys are used to create the Device Signature, i.e. the outer signature of an MTB (see MTS1² of the BoB Standard).

POST /device-challenges

• Post an app public key (in JWK format) to retrieve a device challenge

POST /device-keys

1. Post the challenge and the challenge signature (in P1363 format). Note: The P1363 format specifies that the r and s components of the signature are concatenated. This format differs from the DER/ASN.1 standard.

   1. The user agent client hint request headers (SecSH-UA et al.) can be used to specify the branding and version of the user-agent making the request; see MDN Web Docs page describing the Sec-SH-UA header³ for further details.

2. A Device ID is returned upon successful challenge signature validation

   1. The Device ID is to be used in the field did of the Device Signature Protected Header.

   2. It is also used in subsequent calls to the Samtrafiken Connect API, endpoints POST /ticket-bundles and PATCH /ticket-bundles/{ticketBundleId}

3. If user agent client hint headers were provided in the request, a user agent ID (ua) is returned

   1. Use this user agent ID in the field ua in the Device Signature Protected Header of the MTB. The ID will then be available to a validator validating the MTB.

   2. The user agent ID can later on be used to get the information sent in via the user agent client hint headers. This may help pinpointing errors as information about the ticket bearer device, such as device model, operating system, app and app version, becomes available to the ticket issuer.

4. An encrypted Device Key is returned

   1. Store the Device Key encrypted on the device

   2. Use the app private key to decrypt it

   3. Use the Device Key to create the Device Signature of the MTB

GET /user-agents

• Retrieves the complete set of user agents

GET /user-agents/{ua}

• Retrieves a specific user agent

Samtrafiken Connect API

GET /participants

• Retrieves information about connected Participants (ticket issuers), including details on the traveller categories and product categories they offer

GET /participants/{pid}

• Retrieves information about a specific connected Participant

POST /alternatives

• Find ticket alternatives matching specified criteria

• Alternatives contain one or more products, which represent offerings from the ticket issuer

• An Alternative may contain several products from a single ticket issuer

• An Alternatives expiry date-time is set to the earliest product expiry date-time. If no products have an expiry date-time, the end of the current UTC day is used as default (i.e., 23:59:59 UTC).

GET /alternatives/{alternativeId}

• Retrieves a previously fetched Alternative

POST /manifests

• Generates a Manifest from a specified selection of Alternatives. A Manifest serves as a binding contract, confirming that a ticket meeting the selected Alternative can be issued.

GET /manifests/{manifestId}

• Retrieves a previously fetched Manifest

POST /ticket-bundles

Fetch a Ticket Bundle containing tickets corresponding to theMmanifest received in the preceding manifest call

• The Manifest

• The startOfValidity property states the date and time for the start of the relative validity, i.e. the time frame in which the ticket is valid for travelling

• The deviceId must be provided by the client, this ties the MTB to a specific device. Note: since it is mandatory to provide a Device ID, it follows that no tickets can be issued to non-app clients.

• The signatureLifetime enables clients to request a shorter signature expiry

• The MTB returned by Samtrafiken is signed using Samtrafiken’s MTB Signing Key

• The signatureExpiresAt returned by Samtrafiken indicates when the MTB issuer signature expires and must be updated.