# API Basics
source: https://developer.mastercard.com/benefit-allocation-service-mtls/documentation/api-basics/index.md

Warning: **Key Expiry:** Verify the date your certificates and keys expire. To generate a new set, go to your project dashboard and under API Keys select **Add Key**.

## Client Authentication {#client-authentication}

The Benefit Allocation Service API uses Mutual TLS (mTLS) for client authentication. With mTLS, your client application must present a valid certificate to establish secure, authenticated communication with the API.

For detailed instructions on configuring mTLS authentication, generating certificates, and setting up your client, see [Using MTLS to Access Mastercard APIs](https://developer.mastercard.com/platform/documentation/security-and-authentication/using-mtls-to-access-mastercard-apis/).

You can manage your mTLS certificates from your [Mastercard Developers dashboard](https://developer.mastercard.com/dashboard) after creating a project with the Benefit Allocation Service.

## 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 encrypted by default when transmitted across networks.

## Payload Encryption {#payload-encryption}

The Benefit Allocation Service uses JWE (JSON Web Encryption) to provide end-to-end payload encryption for sensitive data such as Personally Identifying Information (PII).

### Encryption Details {#encryption-details}

* **Key Encryption Algorithm:** RSA_OAEP_256
* **Content Encryption Algorithm:** A256GCM
* **Transport Security:** All communication is encrypted using TLS/SSL by default

For comprehensive guidance on implementing payload encryption in your requests, including sample code and configuration, see [Securing Sensitive Data Using Payload Encryption](https://developer.mastercard.com/platform/documentation/security-and-authentication/securing-sensitive-data-using-payload-encryption/).

Mastercard provides open-source client libraries for [encryption](https://developer.mastercard.com/platform/documentation/security-and-authentication/generating-and-configuring-a-mastercard-api-client/#step-5-add-the-client-encryption-library-to-the-project) that handle the encryption/decryption process automatically.

|                      |                                                                   ![Java](https://static.developer.mastercard.com/content/platform/img/java.svg "Java")                                                                   |                                                              ![C#](https://static.developer.mastercard.com/content/platform/img/csharp.svg)                                                               |                                                ![Python](https://static.developer.mastercard.com/content/platform/img/python.svg)                                                 |                                                ![Node.js](https://static.developer.mastercard.com/content/platform/img/nodejs.svg)                                                 |
|----------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **Download/install** | [![Java version](https://img.shields.io/maven-central/v/com.mastercard.developer/client-encryption.svg?style=flat&color=f99f1c&label=)](https://central.sonatype.com/artifact/com.mastercard.developer/client-encryption) | [![C# version](https://img.shields.io/nuget/v/Mastercard.Developer.ClientEncryption.Core.svg?style=flat&color=f99f1c&label=)](https://www.nuget.org/packages/Mastercard.Developer.ClientEncryption.Core/) | [![Python version](https://img.shields.io/pypi/v/mastercard-client-encryption.svg?style=flat&color=f99f1c&label=)](https://pypi.org/project/mastercard-client-encryption/)        | [![Node.js version](https://img.shields.io/npm/v/mastercard-client-encryption.svg?style=flat&color=f99f1c&label=)](https://www.npmjs.com/package/mastercard-client-encryption)     |
| **View on GitHub**   | [![Java GitHub stars](https://img.shields.io/github/stars/Mastercard/client-encryption-java.svg?label=&style=social)](https://github.com/Mastercard/client-encryption-java)                                               | [![C# GitHub stars](https://img.shields.io/github/stars/Mastercard/client-encryption-csharp.svg?label=&style=social)](https://github.com/Mastercard/client-encryption-csharp)                             | [![Python GitHub stars](https://img.shields.io/github/stars/Mastercard/client-encryption-python.svg?label=&style=social)](https://github.com/Mastercard/client-encryption-python) | [![Node.js GitHub stars](https://img.shields.io/github/stars/Mastercard/client-encryption-nodejs.svg?label=&style=social)](https://github.com/Mastercard/client-encryption-nodejs) |

To get started, add the package that matches your application development language to your project. You can also refer to the client library `README.md` files for detailed how-to information.

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

### Option 1: Generate a Mastercard API Client (Recommended) {#option-1-generate-a-mastercard-api-client-recommended}

Create a customizable API client from the Benefit Allocation Service OpenAPI specification. This approach provides maximum flexibility while leveraging Mastercard's open-source client libraries for mTLS authentication and JWE encryption.

**Steps:**

1. Download the OpenAPI specification: [spec-benefit-allocations.yaml](https://static.developer.mastercard.com/content/benefit-allocation-service-mtls/swagger/spec-benefit-allocations.yaml) (26KB)
2. Generate an API client with [OpenAPI Generator](https://openapi-generator.tech/docs/installation), using the development framework of your choice:

* Sh

```sh
openapi-generator-cli generate -g java -i spec-benefit-allocations.yaml -o api_client
```

3. Follow the [Generating and Configuring a Mastercard API Client](https://developer.mastercard.com/platform/documentation/security-and-authentication/generating-and-configuring-a-mastercard-api-client/) guide
   * **Important:** When asked to select an authentication method, choose **Mutual TLS (mTLS)** --- not OAuth

This approach automatically handles mTLS certificate configuration and encryption/decryption, reducing integration complexity.

### Option 2: Use Your Own REST Client {#option-2-use-your-own-rest-client}

The Benefit Allocation Service exposes a standard REST API that works with any HTTP client. You can still leverage Mastercard's open-source libraries for mTLS and encryption:

* [mTLS Client Authentication Library](https://developer.mastercard.com/platform/documentation/security-and-authentication/using-mtls-to-access-mastercard-apis/#client-certificates-and-environments)
* [JWE Encryption Library](https://developer.mastercard.com/platform/documentation/security-and-authentication/securing-sensitive-data-using-payload-encryption/#client-libraries)

Refer to the [API Reference](https://developer.mastercard.com/benefit-allocation-service-mtls/documentation/api-reference/index.md) for complete endpoint specifications.

### Correlation ID {#correlation-id}

The correlation ID is a unique identifier assigned to each API request and propagated across downstream systems for traceability.

To retrieve it:

1. Make your REST API call as usual.
2. Inspect the HTTP response headers.
3. Look for the `X-Correlation-Id` header.

**Example:**

```text
HTTP/1.1 200 OK
Content-Type: application/json
X-Correlation-Id: 0.b6f2717.1776750106.19f2f20f
```

Use this value when engaging Mastercard support or when logging/tracking correlation across systems.

## Environments {#environments}

| **Environment** |                          **Base URL**                          |                **Auth \& Encryption**                |                                                                                                                                                                                                                                                  **Description**                                                                                                                                                                                                                                                   |
|-----------------|----------------------------------------------------------------|------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Sandbox         | `https://mtf.services.mastercard.com/loyalty/benefits/sandbox` | mTLS + JWE --- no environment-specific configuration | Early-access environment that validates your mTLS certificate and JWE encryption configuration and returns a fixed generic mock response. It does not process real card or benefit data and should not be used for full integration testing. Use your Sandbox mTLS certificates to authenticate with this environment. The certificates are generated when you create your project. To access Sandbox select Benefit Allocation Service when setting up [My Projects](https://developer.mastercard.com/dashboard). |
| MTF             | `https://mtf.services.mastercard.com/loyalty/benefits`         | mTLS + JWE --- no environment-specific configuration | Pre-production test environment containing the latest pre-release version of the real APIs, intended for full integration testing prior to moving to production. Use your Sandbox mTLS certificates for authentication.                                                                                                                                                                                                                                                                                            |
| Production      | `https://services.mastercard.com/loyalty/benefits`             | mTLS + JWE --- no environment-specific configuration | In production you can access the Benefit Allocation Service production services. To access production you need to select [Request Production Access](https://developer.mastercard.com/dashboard) in the Benefit Allocation Service project you have setup.                                                                                                                                                                                                                                                         |

All configured environments require valid mTLS certificates and support JWE payload encryption.

### Next Steps {#next-steps}

Now that you have an understanding of the service's authentication and encryption, proceed to the [Use Cases](https://developer.mastercard.com/benefit-allocation-service-mtls/documentation/use-cases/index.md) section to learn how to access the API and generate your credentials.