# How to install and configure the Insomnia Tool source: https://developer.mastercard.com/cross-border-services/documentation/tutorials/insomnia-tutorial/index.md ## Overview {#overview} Insomnia is a free and open source REST client application on Linux, Mac and Windows operating systems. This tutorial will show you how to use Insomnia with the Mastercard authentication plugin to make an API call. ### You will learn how to: {#you-will-learn-how-to} * Install Insomnia * Install the Mastercard plugin for Insomnia * Configure environment variables and Mastercard API keys * Invoke a Mastercard API from Insomnia ## Install Insomnia {#install-insomnia} * Download [Insomnia](https://insomnia.rest/download/) application for your operating system. * Install and launch the application. You should see the following user interface. ![Alt text](https://static.developer.mastercard.com/content/cross-border-services/uploads/ins-1.png) ## Install the Mastercard Plugin for Insomnia {#install-the-mastercard-plugin-for-insomnia} 1. Download the `insomnia-plugin-mastercard.zip` file from the plugin's [Latest Release](https://github.com/Mastercard/insomnia-plugin-mastercard?tab=readme-ov-file). 2. Click **Show Plugin Folder** button in **Insomnia → Preferences → Plugins** tab. 3. Create a new folder called **insomnia-plugin-mastercard** in the **Plugins** folder. ## Configure Environments {#configure-environments} The Mastercard plugin for Insomnia will add the authorization header for Mastercard APIs when the following environment variable mastercard is set, ```java { "mastercard": { "consumerKey": "000000000000000000000000000000000000000000000000!000000000000000000000000000000000000000000000000", "keyAlias": "keyalias", "keystoreP12Path": "/path/to/sandbox-signing-key.p12", "keystorePassword": "keystorepassword" } } ``` Note: Make sure that `Auth` is set to `None` by clicking the `Auth` dropdown. Otherwise it might interfere with the plugin. ## Encryption Support {#encryption-support} The plugin can take care of encrypting requests and/or decrypting response payloads. To enable encryption support, you need to configure in the environment the `encryptionConfig` property. Here is a quick example for JWE Encryption: ```java "encryptionConfig": { "paths": [ { "path": "/*", "toEncrypt": [ { "element": "$", "obj": "encrypted_payload" } ], "toDecrypt": [ { "element": "encrypted_payload", "obj": "data" } ] } ], "mode": "JWE", "encryptedValueFieldName": "data", "encryptionCertificate": "/path/to/the/encryption/certificate", "keyStore": "/path/to/the/keystore", "keyStoreAlias": "aliasName", "keyStorePassword": "aliasPassword" } ``` [See more examples here](https://github.com/Mastercard/insomnia-plugin-mastercard/tree/main/docs/configuration-examples.md). For more details on the encryption configurations, see these links: * [JWE Encryption](https://github.com/Mastercard/client-encryption-nodejs/blob/main/README.md#configuring-the-jwe-encryption) ### Next {#next} You can create multiple environments in your workspace to store different configurations. For example, create one for Sandbox and one for Production to have them store different key information. For your convenience, we prepared a simple workspace template with the above environment configurations for you to simply import into your Insomnia app. Go to the next page for instructions. ## Using the Mastercard API Workspace Template {#using-the-mastercard-api-workspace-template} ## Manage Environments {#manage-environments} In the Environments dropdown menu, select the appropriate sub environment. ![Alt text](https://static.developer.mastercard.com/content/cross-border-services/uploads/ins-3.png) You can see the Environment variables with placeholder values. We need to fill in the real values with your API key. ## Encryption Support {#encryption-support-1} The plugin can take care of encrypting requests and/or decrypting response payloads. To enable encryption support, you need to configure in the environment the `encryptionConfig` property. Here is a quick example for JWE Encryption: * Java ```java { "host": "https://mtf.api.mastercard.com/crossborder/partners/", "mastercard": { "consumerKey": "000000000000000000000000000000000000000000000000!000000000000000000000000000000000000000000000000", "keyAlias": "keyalias", "keystoreP12Path": "/path/to/sandbox-signing-key.p12", "keystorePassword": "keystorepassword", "encryptionConfig": { "paths": [ { "path": "/*", "toEncrypt": [ { "element": "$", "obj": "encrypted_payload" } ], "toDecrypt": [ { "element": "encrypted_payload", "obj": "data" } ] } ], "mode": "JWE", "encryptedValueFieldName": "data", "encryptionCertificate": "/path/to/the/encryption/certificate", "keyStore": "/path/to/the/keystore", "keyStoreAlias": "aliasName", "keyStorePassword": "aliasPassword" } } } ``` ## Fill In API Keys {#fill-in-api-keys} * Sign in to Mastercard Developers. Create a Project with the APIs you would like to use (for example, Locations) or use an existing Project. ![Alt text](https://static.developer.mastercard.com/content/cross-border-services/uploads/ins-5.png) ![Alt text](https://static.developer.mastercard.com/content/cross-border-services/uploads/ins-6.png) * Fill in the details of your **Consumer Key, Path to Keystore (.p12), Key Alias and Keystore Password**. See the example below for the Sandbox environment. You can do the same for Production environment if you have an approved Production key. ![PRO](https://static.developer.mastercard.com/content/cross-border-services/uploads/pro-screenshot.png) * Click **Done** to close the Manage Environments dialog. Now, you are ready to call the APIs that are authorized by the key you fill in. ## How to call Mastercard API {#how-to-call-mastercard-api} Follow the steps in this How to install and configure the Insomnia Tool tutorial to set up your workspace. You can use this sample YAML collection or your own payload: [cross_border-insomnia.yaml](https://static.developer.mastercard.com/content/cross-border-services/swagger/cross_border-insomnia.yaml) (30KB) To call a Mastercard API, you can either 1. Export your postman collection to a file. You can use the sample YAML collection linked above, or an existing Mastercard collection. Warning: Placeholder pending SME input: the HAR collection link is missing. Confirm whether a HAR export is available for Cross-Border Services or whether the YAML collection is the only supported import. 2. Import it to the Mastercard API workspace in Insomnia. ![Alt text](https://static.developer.mastercard.com/content/cross-border-services/uploads/ins-9.avif) 1. Add a new request by selecting **HTTP Request** in the request dropdown menu. ![Alt text](https://static.developer.mastercard.com/content/cross-border-services/uploads/ins-10.avif) 2. In the request URL field, input the endpoint URL. As mentioned before, we can use the host environment variable as the base URL. Type `{{host}}` in the box. Insomnia will auto prompt you the available matching variable. ![Alt text](https://static.developer.mastercard.com/content/cross-border-services/uploads/ins-11.avif) 3. Complete the URL. In this example, it's `{{host}}/oauth-petstore/pets/dogs`. ![Alt text](https://static.developer.mastercard.com/content/cross-border-services/uploads/ins-12.avif) 4. Add query parameters in the Params tab. If an API needs request body, you can put it in the Body tab. ![Alt text](https://static.developer.mastercard.com/content/cross-border-services/uploads/ins-13.avif) 5. It's all set. Click the Send button to submit the request and get the response back. ![Alt text](https://static.developer.mastercard.com/content/cross-border-services/uploads/ins-14.avif)