# 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 [payload 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). Configure mTLS in the generated client's underlying HTTP client using your project certificate; Mastercard does not currently provide an mTLS authentication library.

#### Java JWE configuration {#java-jwe-configuration}

The Mastercard client-encryption library uses a JWE configuration to encrypt request payloads into the `encryptedValue` field. Load the encryption certificate downloaded for your project, then configure the generated client's HTTP client with the JWE interceptor:

```java
Certificate encryptionCertificate = EncryptionUtils.loadEncryptionCertificate(
   encryptionCert.getAbsolutePath());

JweConfig jweConfig = JweConfigBuilder.aJweEncryptionConfig()
   .withEncryptionCertificate(encryptionCertificate)
   .withEncryptedValueFieldName("encryptedValue")
   .build();

OkHttpClient.Builder httpClientBuilder = apiClient.getHttpClient().newBuilder();
apiClient.setHttpClient(
   httpClientBuilder
      .addInterceptor(new OkHttpJweInterceptor(jweConfig))
      .build());
```

This shows the JWE setup only; configure the HTTP client's mTLS certificate separately as described in the [client-generation tutorial](https://developer.mastercard.com/benefit-allocation-service-mtls/tutorial/generate-client/step4/index.md).

|                      |                                                                   ![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}

### Generate a Mastercard API Client {#generate-a-mastercard-api-client}

Create a customizable API client from the Benefit Allocation Service OpenAPI specification. Configure the generated client's HTTP transport for mTLS and use Mastercard's client-encryption library for JWE payload 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) (27KB)
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

The generated client provides the endpoint methods and data models. Configure mTLS in its underlying HTTP client and JWE using the configuration above. Refer to the [API Reference](https://developer.mastercard.com/benefit-allocation-service-mtls/documentation/api-reference/index.md) for 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. Responses reflect values in the request, but Sandbox 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 [Quick Start Guide](https://developer.mastercard.com/benefit-allocation-service-mtls/documentation/quick-start-guide/index.md) section to learn how to access the API and generate your credentials.