# Quick Start Guide
source: https://developer.mastercard.com/mastercard-threat-intelligence/documentation/quick-start-guide/index.md

## Overview {#overview}

Mastercard Threat Intelligence (MTI) provides a suite of APIs that deliver actionable threat intelligence insights across the payment ecosystem. These APIs enable issuers and acquirers to proactively identify and mitigate risks such as card testing, merchant fraud, and payment vulnerabilities.

This guide gets you from zero to your first Mastercard Threat Intelligence API call in the Sandbox environment. By the end, you will have access to the API, a project with Sandbox credentials, and a successful first request.
Tip: If you want the fastest path to a working Sandbox request, start with the [Insomnia collection](https://developer.mastercard.com/mastercard-threat-intelligence/documentation/developer-tools/insomnia-collection/index.md) or [Postman collection](https://developer.mastercard.com/mastercard-threat-intelligence/documentation/developer-tools/postman-collection/index.md). They let you test Sandbox and Production flows without writing code first.

### You can follow this guide to Production Readiness {#you-can-follow-this-guide-to-production-readiness}

* Get access to the Mastercard Threat Intelligence API.
* Create a project and generate Sandbox credentials.
* Make your first Sandbox request and read the response.
* Understand how to test and how to promote the project to Production.

> ### Before you begin {#before-you-begin}
>
> * Create a [Mastercard Developers](https://developer.mastercard.com/) account.
> * Have a secure place to store downloaded OAuth and encryption keys.
> * Decide how you want to test: [Postman](https://developer.mastercard.com/mastercard-threat-intelligence/documentation/developer-tools/postman-collection/index.md), [Insomnia](https://developer.mastercard.com/mastercard-threat-intelligence/documentation/developer-tools/insomnia-collection/index.md), the [Reference application](https://developer.mastercard.com/mastercard-threat-intelligence/documentation/developer-tools/reference-app/index.md), or your own client.
> * Review [API Basics](https://developer.mastercard.com/mastercard-threat-intelligence/documentation/api-basics/index.md) to understand OAuth 2.0 authentication, DPoP, environments and security requirements, and ensure you have an OAuth 2.0 signing method ready, such as a Mastercard OAuth library or a configured Postman or Insomnia workspace.
> * Access the OpenAPI specification from [here](https://static.developer.mastercard.com/content/mastercard-threat-intelligence/swagger/mastercard-threat-intelligence-api.yaml).

### Sandbox Checklist {#sandbox-checklist}

| Step |                                Task                                | Done |
|------|--------------------------------------------------------------------|------|
| 1    | Create or sign in to your Mastercard Developers account            | ☐    |
| 2    | Create a project and select the Mastercard Threat Intelligence API | ☐    |
| 3    | Generate and download your Sandbox signing key                     | ☐    |
| 4    | Record your client ID, key ID, and scopes                          | ☐    |
| 5    | Obtain an access token and DPoP proof                              | ☐    |
| 6    | Make your first Sandbox request                                    | ☐    |
| 7    | Run a negative test to confirm error handling                      | ☐    |

## Get access to the API {#get-access-to-the-api}

1. Go to [Mastercard Developers](https://developer.mastercard.com/) and create an account.
2. Activate your account by opening the link sent to your email address, and log in.
3. Open your [My Projects](https://developer.mastercard.com/dashboard) page and start a new project. Sandbox access is open, so you can begin testing as soon as your project credentials are generated.

## Create a project and generate Sandbox credentials {#create-a-project-and-generate-sandbox-credentials}

Create a Mastercard Developers project to generate your Sandbox credentials. Sandbox gives you mocked data so you can validate your integration before requesting Production access.

1. Go to [My Projects](https://developer.mastercard.com/dashboard) and click **Create Project**
2. Enter your project name
3. Indicate if you are creating the project on behalf of a client  
   Note: Select "Yes" if you are a service provider creating the integration on behalf of issuers and acquirers.
4. Provide client company details (if applicable)
5. Select the **Mastercard Threat Intelligence API service**   
   ![quick-start-guide](https://static.developer.mastercard.com/content/mastercard-threat-intelligence/uploads/quick-start-guide-create-project.png)
6. Proceed to create your 'Project Credentials'. By default, OAuth 2.0 project keys will be created. Scroll down and create a key alias and keystore password, **take note of these** . ![quick-start-guide](https://static.developer.mastercard.com/content/mastercard-threat-intelligence/uploads/quick-start-guide-create-project-2.png)
7. Click on Create Project.
8. Download your OAuth keys, and **store them in a safe place** . Click on Open Project. ![quick-start-guide](https://static.developer.mastercard.com/content/mastercard-threat-intelligence/uploads/quick-start-guide-create-project-3.png)
9. Once you complete this flow, you will land on the Project page. From the Project page, take note of your: 1) Sandbox and Production status ('Ready/ Not Requested'), 2) Sandbox and Production credentials: authentication consumer key.

Tip: For more information, see [Credential Management](https://developer.mastercard.com/platform/documentation/credential-management/oauth-key-management/).

## Make Your First Sandbox Request {#make-your-first-sandbox-request}

The simplest first call is the Search Vulnerabilities endpoint, because it uses a GET request with query parameters.

#### Obtain an Access Token and DPoP Proof {#obtain-an-access-token-and-dpop-proof}

Before calling any Mastercard Threat Intelligence API endpoint, you must obtain:

* An OAuth 2.0 access token
* A DPoP proof for the request

The easiest way to generate both is by using the [Postman collection](https://developer.mastercard.com/mastercard-threat-intelligence/documentation/developer-tools/postman-collection/index.md).

1. Review the authentication model in [API Basics](https://developer.mastercard.com/mastercard-threat-intelligence/documentation/api-basics/index.md).
2. Open the [Postman collection](https://developer.mastercard.com/mastercard-threat-intelligence/documentation/developer-tools/postman-collection/index.md).
3. Complete the Sandbox authentication flow to:
   * Generate a DPoP proof
   * Request an OAuth 2.0 access token
4. Copy the generated values for:
   * `ACCESS_TOKEN`
   * `DPOP_PROOF`
5. Return to this guide and use those values in the Sample Request below.

Tip: If you prefer to automate authentication in your application, refer to the Mastercard OAuth 2.0 libraries and the information in [API Basics](https://developer.mastercard.com/mastercard-threat-intelligence/documentation/api-basics/index.md).

### Prerequisites for the Request {#prerequisites-for-the-request}

Every request needs two authentication headers:

* `Authorization: DPoP <access_token>`
* `DPoP: <dpop_proof>`

You generate the access token and DPoP proof from your credentials. The Mastercard OAuth 2.0 client library produces both for you. A raw cURL request cannot create a DPoP proof on its own, so generate these values first, then run the command below.

### Sample Request {#sample-request}

```bash
curl -X GET \
  "https://sandbox.cyber.mastercard.com/exposures/vulnerabilities?severity_label=High&limit=5" \
  -H "Authorization: DPoP ${ACCESS_TOKEN}" \
  -H "DPoP: ${DPOP_PROOF}" \
  -H "Accept: application/json"
```

### Expected Response {#expected-response}

A successful call returns `200 OK` with a page of vulnerabilities:

```json
{
  "records": [
    {
      "cveId": "CVE-2018-7600",
      "riskScore": 95,
      "severityLabel": "High",
      "lifecyclePhase": "Exploited",
      "affectedProducts": ["Website Tool 7.x"]
    }
  ],
  "page": { "limit": 5, "offset": 0, "total": 1 }
}
```

### Negative Test {#negative-test}

Send an invalid value to confirm your error handling. For example, set `severity_label=Hi`, which is shorter than the minimum length:

```bash
curl -X GET \
  "https://sandbox.cyber.mastercard.com/exposures/vulnerabilities?severity_label=Hi" \
  -H "Authorization: DPoP ${ACCESS_TOKEN}" \
  -H "DPoP: ${DPOP_PROOF}" \
  -H "Accept: application/json"
```

The API returns `400 Bad Request`:

```json
{
  "error": "BAD_REQUEST",
  "error_description": "Field 'filters.searchText' must be between 1 and 256 characters"
}
```

A missing or invalid token returns `403 Forbidden` with `error: THREAT_INTELLIGENCE_FORBIDDEN_ERROR`.

## Choose How You Want to Test and Integrate {#choose-how-you-want-to-test-and-integrate}

Pick the approach that fits your workflow:

* **Generated client (recommended).** Generate a client from the OpenAPI specification and add the Mastercard OAuth 2.0 client library. The step-by-step build is documented [here](https://developer.mastercard.com/mastercard-threat-intelligence/tutorial/api-sandbox-guide/index.md).
* **Postman or Insomnia.** Import [Mastercard Threat Intelligence API specs](https://static.developer.mastercard.com/content/mastercard-threat-intelligence/swagger/mastercard-threat-intelligence-api.yaml) to explore the endpoints. Configure the OAuth 2.0 authorization and DPoP headers before you send requests. See here for [Insomnia collection](https://developer.mastercard.com/mastercard-threat-intelligence/documentation/developer-tools/insomnia-collection/index.md) and [Postman collection](https://developer.mastercard.com/mastercard-threat-intelligence/documentation/developer-tools/postman-collection/index.md) details for the Mastercard Threat Intelligence API.
* **Reference application.** Use the reference application provided [here](https://developer.mastercard.com/mastercard-threat-intelligence/documentation/developer-tools/reference-app/index.md).

## Promote the Same Project to Production {#promote-the-same-project-to-production}

Alert: To get approved for Production access, your organization must be enrolled in the Mastercard Threat Intelligence product. If you already use Mastercard Threat Intelligence through [Mastercard Connect](https://www.mastercardconnect.com/), the approval process may be expedited. If your organization is not currently enrolled, the Mastercard Threat Intelligence product team will contact you regarding the next steps required to obtain Production access.

The following criteria define the expected inputs and outcomes for each stage of the onboarding process.

### Required Information for Production Approval {#required-information-for-production-approval}

Use the same project you created for Sandbox as the basis for Production. Before submitting a Production access request, ensure the following information is available:

#### Required {#required}

* Company ID (CID) associated with your Mastercard Developers profile.
* Confirmation that your organization is enrolled in the Mastercard Threat Intelligence product.
* Intended production use case.
* Commercial countries where the service will be used.
* OAuth 2.0 project credential information.
* Customer organization details (if requesting access on behalf of a customer).
* Acceptance of all applicable terms and conditions.

#### Optional {#optional}

* Interbank Card Association (ICA) numbers to associate with the client ID.

### Request Production Access {#request-production-access}

1. Open your project and request Production access for the Mastercard Threat Intelligence API.
2. Provide the required onboarding information listed above.
3. Optionally, specify the ICA numbers you want associated with the client ID. This updates the default base filter to restrict datasets based on the Company ID (CID) associated with your Mastercard Developers profile and the approved ICA list.
4. Select the commercial countries where the service will be used.
5. Accept the applicable terms and conditions.
6. Verify the OAuth 2.0 project credential information.
7. Submit the Production access request for review.

### Production Onboarding \& Enrollment {#production-onboarding--enrollment}

#### Production Review Timeline {#production-review-timeline}

Production access requests are reviewed after all required onboarding information has been submitted.

Production requests are typically processed within **5 business days**. Review times may vary depending on:

* Validation of product enrollment status.
* Verification of Company ID (CID) information.
* Completeness of the submitted request.
* Additional contractual, compliance, or onboarding requirements.

If additional information is required, the review timeline may be extended until the requested information is received.

#### Approval Process {#approval-process}

**Entry Criteria**

* Production access request has been submitted.
* Required onboarding information has been provided.

**Exit Criteria**

* Production access request is approved.

* Production credentials become available within the project.

* Once you submit a Production access request, the Mastercard Threat Intelligence product team will review the submission.

* If your organization is already enrolled with the Mastercard Threat Intelligence UI in [Mastercard Connect](https://www.mastercardconnect.com/), the review process typically consists of validating the Company ID (CID) and any optional ICA information provided.

* If your organization is not currently enrolled, the product team will contact you regarding the next steps required to obtain Production access.

* Ensure that a valid Company ID (CID) is associated with your Mastercard Developers profile before submitting a Production access request.

### Production Go-Live {#production-go-live}

**Entry Criteria**

* Production credentials have been issued.
* Production base URL is configured.
* Production authentication configuration is completed.

**Exit Criteria**

* Production authentication is validated.
* Successful Production API requests are completed.
* Integration is ready for operational use.

After approval:

1. Production credentials will become available within your project.
2. Update your application configuration to use the Production base URL, `https://cyber.mastercard.com`.
3. Configure your application using the issued Production credentials.
4. Validate authentication and connectivity in the Production environment before operational use.

## Next Steps {#next-steps}

* Read the [API Basics](https://developer.mastercard.com/mastercard-threat-intelligence/documentation/api-basics/index.md) for authentication, transport encryption, and environment details.
* Explore the other features: merchant domain risk and card testing intelligence.
* Add filters, sorting, and pagination to narrow your search results.
* Build the intelligence data into your fraud, cyber-security, and risk workflows.