# How to make APIM API Calls

## Environments

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

| Environment | External Hostname |
|  --- | --- |
| Test | N/A |
| Acceptance | api-ovpay-acc.translink.nl |
| Production | api-ovpay.translink.nl |


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.

![Figure 1](/assets/apim_b2b.a462fede82f99763d2e4440cff97dbcb578640e05814a747eb441893df4a2677.6dc3f85a.png)

## 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](https://learning.postman.com/docs/sending-requests/authorization/certificates/).

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:

![Figure 2](/assets/postman1.228096cba5b721c05c62bfcf69d94cf80a2eda64fcea4ad7f5754e9d7fd02d7d.6dc3f85a.png)

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

![Figure 3](/assets/postman2.7f3b4fbf5de1f4f94384edf1cc78d0fff8a3a489da5d94390f7f6e26cbb37f2d.6dc3f85a.png)

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:


```json
{
 "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](https://learning.postman.com/docs/sending-requests/authorization/certificates/).

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.

![Figure 4](/assets/postman3.23e352b338c829f1c6a8c68491a688a766767ae36358a01cc51dd65e876bb7ab.6dc3f85a.png)

* 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](/content/api-reference)