How to make APIM API Calls

Environments

The BASE-URLs used for the different APIM environments are:

The following security measures are in place:

1. mTLS (mutual TLS) is mandatory for all communication, requiring the client to provide a valid client certificate.
2. A subscription is required that grants access to a product with one or more APIs. The subscription has an Apikey which needs to be send with every request in the Apikey header.
3. A JWT access token is required. The client will need a client id & secret to retrieve an access token via the B2B Client Authentication API. It can then be passed with other requests via the Authorization header.

The following sequence diagram shows an example where the client first retrieves an access token, and then calls another API to retrieve data.

Get access token

The B2B Client Authentication API can be used to retrieve an access token. As a client, you’ll need a client id & secret. You’ll also need a subscription to the B2B Client Authentication product for the Apikey.

To retrieve an access token, you’ll need to perform a POST on https://hostname/b2b-client-authentication/v1/token , where {hostname} is the environment specific internal/external hostname. For example: https://api-ovpay.translink.nl/b2b-client-authentication/v1/token.

Example

Instruction on how to configure a client certificate in Postman for mTLS can be found in the official Postman documentation: Add and manage CA and client certificates in Postman | Postman Learning Center.

The client id & secret must be set in the request body, which is in the x-www-form-urlencoded format. The grant_type should be client_credentials. See the following figure:

The Apikey of your subscription to the B2B Client Authentication product must be specified in the Apikey header:

When a valid client id & secret are provided, the response will look similar to the example below. The acess_token can be used when performing other requests:

{
 "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOi.....TRUNCATED.....Z_4S9SF7VpVfa90tj_jVL2ftpYYmwQ",
 "expires_in": 60,
 "refresh_expires_in": 0,
 "token_type": "Bearer",
 "not-before-policy": 0,
 "scope": ""
}

Call other APIs

After retrieving an access token, you can use it to call other APIs. In order to provide a valid Apikey, you’ll need a subscription to a product that includes the API that you want to call. Please note that you cannot reuse the Apikey of the subscription to the B2B Client Authentication product.

Examples

The following section provides an example on how to call an API named ‘example’ and retrieve some data with a specific id. The {hostname} is the environment specific internal/external hostname. For example: https://api-ovpay.translink.nl/example/v1/data/123.

Instruction on how to configure a client certificate in Postman for mTLS can be found in the official Postman documentation: Add and manage CA and client certificates in Postman | Postman Learning Center.

As shown in the figure below, the Apikey of the subscription must be specified in the header. The access token is a bearer token and must specified in the Authorization header.

• The /example/v1/data/{id} endpoint doesn't exist, so you'll get 404 Resource Not Found response. You'll need to provide a valid url. These URLs can be found on in the API reference