# API Basics
source: https://developer.mastercard.com/mastercard-threat-intelligence/documentation/api-basics/index.md

## Overview {#overview}

This section covers what you need to integrate with the Mastercard Threat Intelligence API: how you authenticate, how data is protected in transit, how to consume the API, and which environments are available.

The Mastercard Threat Intelligence API is a REST API. It accepts and returns JavaScript Object Notation (JSON) over HTTPS. Requests use standard HTTP methods, and responses use standard HTTP status codes.

## Client Authentication {#client-authentication}

The Mastercard Threat Intelligence API uses [OAuth 2.0](https://developer.mastercard.com/platform/documentation/authentication/using-oauth-2-to-access-mastercard-apis/) which follows the Financial-grade FAPI 2.0 Security Profile with two elements:

* **Private key JWT client authentication.** You authenticate to the token endpoint with a signed client assertion rather than a shared secret.
* **Demonstrating Proof of Possession (DPoP).** Access tokens are sender-constrained. Each request carries a DPoP proof that binds the token to your key, so a stolen token cannot be replayed.  


What You Need   
To authenticate, you set up the following in your [Mastercard Developers](https://developer.mastercard.com/dashboard) project:

<br />

* A **client ID** that identifies your application.
* An **authentication key pair** . You keep the private key and register the public key with Mastercard. This key signs the `private_key_jwt` client assertion sent to the token endpoint.
* A **DPoP key** pair that your application generates and holds itself. You do not register it with Mastercard. This key signs the DPoP proof sent with each token request and API call.
* A **key ID** (`kid`) that tells Mastercard which registered authentication key to use.
* One or more **scopes** that grant access to specific intelligence domains.

Alert: Keep the private key confidential. Store it in a secrets manager and rotate it on a regular schedule. Never embed it in source control or client-side code.


How the Flow Works   
The API uses the [OAuth 2.0](https://developer.mastercard.com/platform/documentation/authentication/using-oauth-2-to-access-mastercard-apis/) client credentials grant:

<br />

1. Your client builds a client assertion and signs it with your authentication key.
2. Your client requests an access token from the token endpoint.
3. The token endpoint returns a short-lived access token.
4. Your client sends the access token and a DPoP proof, signed with your DPoP key, with every API request.
5. Your client refreshes the token before it expires.

Tip: You do not need to build this flow by hand. The [Mastercard OAuth 2.0 client library](https://github.com/Mastercard/oauth2-client-java) performs client assertion signing, DPoP proof creation, and token caching for you.

## Transport Encryption {#transport-encryption}

The transport between client applications and Mastercard is secured using [TLS/SSL](https://en.wikipedia.org/wiki/Transport_Layer_Security), which means data is secured by default when transmitted across networks.

Responses can contain sensitive intelligence, including merchant identifiers, transaction attributes, and a Primary Account Number (PAN). TLS protects this data in transit. You are responsible for protecting it at rest and controlling access within your organization.
Tip: Do you want to learn more about the authentication and encryption schemes Mastercard uses? Read our [Using OAuth 2.0 to Access Mastercard APIs](https://developer.mastercard.com/platform/documentation/authentication/using-oauth-2-to-access-mastercard-apis/) guide.

## How to Consume the API {#how-to-consume-the-api}

You consume the API by generating a client from the OpenAPI specification and adding OAuth 2.0 authentication. The recommended path is:

1. **Get the OpenAPI specification.** The specification of [Mastercard Threat Intelligence API](https://static.developer.mastercard.com/content/mastercard-threat-intelligence/swagger/mastercard-threat-intelligence-api.yaml) describes every endpoint, request schema, and response schema.
2. **Generate an API client.** Use the OpenAPI Generator to produce a client in your language of choice. For Java, generate with the `okhttp-gson` library so the client pairs cleanly with the Mastercard OAuth 2.0 client library.
3. **Add OAuth 2.0 authentication.** Register the OAuth 2.0 interceptor on the HTTP client that the generator produces. The interceptor attaches access tokens and DPoP proofs to each request.
4. **Configure your credentials.** Supply your client ID, key ID, signing key, scopes, and the environment base URL.
5. **Call the endpoints.** Invoke the generated methods and read the typed response objects.

Tip: For a language-agnostic guide, see [Generating and Configuring a Mastercard API Client](https://developer.mastercard.com/platform/documentation/developer-tools/generating-and-configuring-a-mastercard-api-client/).   
Search, Filter, Sort, and Paginate   

The search endpoints share a consistent request model. You can combine these capabilities to narrow results:

* **Free-text search** across multiple fields with a `searchText` value.
* **Field filters** such as merchant name, merchant ID, terminal ID, institution codes, and severity.
* **Range filters** for dates, transaction amounts, and transaction counts.
* **Sorting** by a chosen field in ascending or descending order.
* **Pagination** with `limit` and `offset`, where the response reports the total number of matching records.

<br />

Error Model   

Errors return a standard JSON body with four fields: `source`, `error`, `recoverable`, and `error_description`. Common status codes include:

* `400 Bad Request`: the request is malformed or a field fails validation.
* `403 Forbidden`: your project lacks access to the requested intelligence domain.

Use the `recoverable` field to decide whether to retry.
Tip: Follow the detailed steps outlined in this tutorial - [Sandbox Integration](https://developer.mastercard.com/mastercard-threat-intelligence/tutorial/api-sandbox-guide/index.md)

## Environment Descriptions {#environment-descriptions}

The table below describes the two different environments that are available.

| Environment |                                                                                                                                                                                                                                                  Description                                                                                                                                                                                                                                                   |
|-------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Sandbox     | `https://sandbox.cyber.mastercard.com` The [Sandbox](https://developer.mastercard.com/mastercard-threat-intelligence/documentation/api-reference/index.md) environment is an open, self-service test environment where developers can experiment with API calls without affecting real data or systems, ensuring that any errors or issues can be safely identified and resolved. Validate connectivity, authentication, request construction, filtering, and response handling before you move to Production. |
| Production  | `https://cyber.mastercard.com` The production environment is the live environment setting where the API interacts with actual users and data environment. To access production, you need to select [Request Production Access](https://developer.mastercard.com/dashboard) in the project you have set up.                                                                                                                                                                                                     |

Environment-specific differences to plan for:

* **Credentials differ by environment.** Your client ID and signing key for Sandbox are separate from those for Production. Configure each environment with its own values.
* **Access is dependent on product enrollment.** Access to specific intelligence domains depends on your organization's enrollment with Mastercard Threat Intelligence product. Complete Sandbox testing before you request Production access.
* **Data differs.** Sandbox returns representative test data. Production returns live intelligence.

## Next Steps {#next-steps}

Review the [Use Cases](https://developer.mastercard.com/mastercard-threat-intelligence/documentation/use-cases/index.md) to understand the available threat Intelligence capabilities and determine:

* Which use cases you plan to integrate with.
* Whether your organization requires issuer or acquirer access.