# Insomnia Collection
source: https://developer.mastercard.com/mastercard-threat-intelligence/documentation/developer-tools/insomnia-collection/index.md

[Insomnia](https://insomnia.rest/) is an open-source API client. Developers use
it to send HTTP requests to Mastercard APIs quickly. This guide shows you how to
set up and run Mastercard Threat Intelligence (MTI) API requests in Insomnia.

The guide covers plugin installation, collection import, environment setup for
the OAuth 2.0 flow, and how to send and validate requests in the Sandbox and
Production environments. OAuth is a standard for authorizing access.

Get the MTI API Insomnia collection here:
[mti-insomnia-collection.json](https://static.developer.mastercard.com/content/mastercard-threat-intelligence/uploads/mti-insomnia-collection.json).

## Prerequisites {#prerequisites}

Confirm you have the following before you start:

* Access to a Mastercard Developers project with the credentials the MTI API requires.
* Insomnia installed on your machine.
* Your OAuth 2.0 details: a client ID, a key ID, a signing key, and the scopes granted to your project.

## What You Will Find {#what-you-will-find}

This guide includes:

* Plugin installation options for Insomnia.
* Import guidance for the MTI collection.
* Environment setup for the OAuth 2.0 flow.
* Steps for sending and validating requests in the Sandbox and Production environments.

## Install the Mastercard Insomnia Plugin {#install-the-mastercard-insomnia-plugin}

Mastercard provides an
[Insomnia plugin](https://github.com/Mastercard/insomnia-plugin-mastercard) that
helps with request authentication. Install it from within Insomnia.

1. Open Insomnia.
2. Go to the application settings and open the **Plugins** tab.
3. In the **Add Plugin** field, enter `insomnia-plugin-mastercard`.
4. Choose **Install Plugin**.

For the full setup, open the
[Insomnia Collection guide](https://developer.mastercard.com/platform/documentation/developer-tools/insomnia-collection/)
on the Mastercard Developers portal.

## Import the Collection {#import-the-collection}

Import the MTI collection to load every request at once.

1. Download [mti-insomnia-collection.json](https://static.developer.mastercard.com/content/mastercard-threat-intelligence/uploads/mti-insomnia-collection.json) from this tutorial.
2. In Insomnia, open the **Create** or **Import** menu.
3. Choose **Import** and then **From File**.
4. Select the downloaded file.

Insomnia creates a collection named **Mastercard Threat Intelligence API**. The
collection groups requests by feature:

* Merchant Threat Intelligence: search merchant domains.
* Payment Ecosystem Threat Intelligence: search high-risk vulnerabilities.
* Card Testing: filter options and the observed testing, testing behaviors, and transactions searches.

## Configure the Environment {#configure-the-environment}

The collection uses environment variables so you do not repeat values in each
request. It ships with a base environment and two sub-environments: **MTI API Sandbox**
and **MTI API Production**.

Open the environment editor and set these values in the base environment:

|      Variable      |                                                                  Description                                                                  |
|--------------------|-----------------------------------------------------------------------------------------------------------------------------------------------|
| `base_url`         | The API base URL. Sandbox: `https://sandbox.cyber.mastercard.com`. Production: `https://cyber.mastercard.com`                                 |
| `tokenEndpoint`    | OAuth 2.0 token endpoint URL. Sandbox: `https://sandbox.api.mastercard.com/oauth/token`. Production: `https://api.mastercard.com/oauth/token` |
| `issuer`           | The OAuth 2.0 issuer. Sandbox: `https://sandbox.api.mastercard.com`. Production: `https://api.mastercard.com`                                 |
| `clientId`         | Your client ID from your Mastercard Developers project.                                                                                       |
| `kid`              | Your key ID from your project.                                                                                                                |
| `scopes`           | The scopes granted to your project.                                                                                                           |
| `keystoreP12Path`  | Your keystore file path from your project resources                                                                                           |
| `keyAlias`         | Your keystore file alias name                                                                                                                 |
| `keystorePassword` | Your keystore file password                                                                                                                   |

Start with the **Sandbox** sub-environment while you build and test.

## Send and Validate Requests {#send-and-validate-requests}

After you set the environment values, run a request.

1. Confirm the active environment is **Sandbox**.
2. Open a request, such as **Search Merchant Domains**.
3. Review the URL, headers, and body.
4. Choose **Send**.

Validate the response:

* A `200 OK` status means the request succeeded. Review the JSON body.
* For the domains request, check the `status` of each report in the body.
* A `400 Bad Request` status means a field is invalid. Read the `error_description` and fix the request.
* A `403 Forbidden` status means your project cannot access that feature.

For details on status codes and error handling, open
[Code and Formats](https://developer.mastercard.com/mastercard-threat-intelligence/documentation/code-and-formats/index.md).

## Switch Between Sandbox and Production {#switch-between-sandbox-and-production}

The collection separates the two environments, so switching is simple.

1. Open the environment selector.
2. Choose **Production**.
3. Update `clientId`, `kid`, `scopes`, `base_url`, `tokenEndpoint`, `keystoreP12Path`, `keyAlias`, `keystorePassword` and `issuer` with your Production values.
4. Send the request again.

Confirm your project has Production access before you send live traffic.

## Run an API endpoint {#run-an-api-endpoint}

After correctly importing the json package and configuring the environment, hit **Send** for an API endpoint to get a successful response.