# API Basics source: https://developer.mastercard.com/benefit-allocations-service/documentation/api-basics/index.md Warning: **Key Expiry:** Verify the date your keys expire. To generate a new set, go to your project dashboard and under API Keys select "Add Key". ## Client Authentication {#client-authentication} Mastercard uses one-legged OAuth 1.0a to authenticate and authorize client applications. To access the Benefit Allocation Service API, you must authenticate your client applications. This means that you have to digitally sign every request sent to Mastercard, and only requests with valid signatures created by authorized clients can gain access to the Benefit Allocation Service. You can manage your authentication keys from your [dashboard](https://developer.mastercard.com/dashboard) after you created a project using Benefit Allocation Service. Tip: Do you want to learn more about the authentication scheme Mastercard uses? For that, read our [Using OAuth 1.0a to Access Mastercard APIs](https://developer.mastercard.com/platform/documentation/security-and-authentication/using-oauth-1a-to-access-mastercard-apis/) guide. ## 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 are encrypted by default when transmitted across networks. In addition to that, Benefit Allocation Service uses JWE to provide end-to-end payload encryption to secure sensitive data like Personally Identifying Information (PII). You can manage your encryption keys from your [Developer Dashboard](https://developer.mastercard.com/dashboard). Tip: Do you want to learn more about the authentication and encryption schemes Mastercard uses? For that, read our [Using OAuth 1.0a to Access Mastercard APIs](https://developer.mastercard.com/platform/documentation/security-and-authentication/using-oauth-1a-to-access-mastercard-apis/) and [Securing Sensitive Data Using Payload Encryption](https://developer.mastercard.com/platform/documentation/security-and-authentication/securing-sensitive-data-using-payload-encryption/) guides. Mastercard provides open-source client libraries for [authentication](https://developer.mastercard.com/platform/documentation/security-and-authentication/generating-and-configuring-a-mastercard-api-client/#step-4-add-the-client-authentication-library-to-the-project) and [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). Internally it uses the below algorithms Key Encryption Algorithm : RSA_OAEP_256 Content Encryption Algorithm : A256GCM ## How to Consume the API? {#how-to-consume-the-api} ### Generating your own Benefit Allocation Service API client {#generating-your-own-benefit-allocation-service-api-client} Create customizable API clients from the Benefit Allocation Service API specification and let Mastercard open-source client libraries handle the authentication for you. This approach offers more flexibility and is strongly recommended. To learn how to generate your own client, please follow our guide: [Generating and Configuring a Mastercard API Client](https://developer.mastercard.com/platform/documentation/developer-tools/generating-and-configuring-a-mastercard-api-client/) using: * The following Benefit Allocation Service API specification file: [spec-benefit-allocations.yaml](https://static.developer.mastercard.com/content/benefit-allocations-service/swagger/spec-benefit-allocations.yaml) (27KB) * An API client library generated using [OpenAPI Generator](https://openapi-generator.tech/docs/installation) and the development framework of your choice (see also: [Generators List](https://openapi-generator.tech/docs/generators/)): * Sh ```sh openapi-generator-cli generate -g java -i spec-benefit-allocations.yaml -o api_client ```
* The following is an example for payload encryption. * Java * Csharp * Javascript * Python * Go ```java PrivateKey signingKey = AuthenticationUtils.loadSigningKey(p12File, keyAlias, keyStorePassword); Certificate encryptionCertificate = EncryptionUtils.loadEncryptionCertificate(encryptionCert); JweConfig config = JweConfigBuilder.aJweEncryptionConfig() .withEncryptionCertificate(encryptionCertificate) .withEncryptionPath("$", "$") .withEncryptedValueFieldName("encryptedValue") .build(); ``` ```csharp // Used for adoption endpoints public JweConfig EncryptionConfigForAdoptions() { var encryptionCertificate = EncryptionUtils.LoadEncryptionCertificate(encryptionCertificateFilePath); var decryptionKey = EncryptionUtils.LoadDecryptionKey(decryptionKeyFilePath, decryptionKeyPassword); return JweConfigBuilder.AJweEncryptionConfig() .WithEncryptionCertificate(encryptionCertificate) .WithDecryptionKey(decryptionKey) .WithEncryptionPath("$.owner", "$.encryptedOwner") .WithDecryptionPath("$.encryptedOwner.encryptedData", "$.owner") .WithDecryptionPath("$.adoption.encryptedOwner.encryptedData", "$.adoption.owner") .Build(); } // Used for employees and payment endpoints public JweConfig FullBodyEncryptionConfig() { var encryptionCertificate = EncryptionUtils.LoadEncryptionCertificate(encryptionCertificateFilePath); var decryptionKey = EncryptionUtils.LoadDecryptionKey(decryptionKeyFilePath, decryptionKeyPassword); return JweConfigBuilder.AJweEncryptionConfig() .WithEncryptionCertificate(encryptionCertificate) .WithDecryptionKey(decryptionKey) .WithEncryptionPath("$", "$") .WithDecryptionPath("$", "$") .Build(); } ``` ```javascript // Used for adoption endpoints function createEncryptionConfigForAdoptions() { return { paths: [ { path: ".*", toEncrypt: [{ element: "owner", obj: "encryptedOwner" }], toDecrypt: [ { element: "encryptedOwner.encryptedData", obj: "owner" }, { element: "adoption.encryptedOwner.encryptedData", obj: "adoption.owner" } ] } ], mode: "JWE", encryptionCertificate: "./path/to/encryptionCertificate.pem", privateKey: "./path/to/decryptionKey.pem" }; } // Used for employees and payment endpoints function createFullBodyEncryptionConfig() { return { paths: [ { path: ".*", toEncrypt: [{ element: "$", obj: "$" }], toDecrypt: [{ element: "$", obj: "$" }] } ], mode: "JWE", encryptionCertificate: "./path/to/encryptionCertificate.pem", privateKey: "./path/to/decryptionKey.pem" }; } const encryptionConfigForAdoptions = createEncryptionConfigForAdoptions(); const fullBodyEncryptionConfig = createFullBodyEncryptionConfig(); ``` ```python from client_encryption.jwe_encryption_config import JweEncryptionConfig # Used for adoption endpoints def build_encryption_config_for_adoptions(): return JweEncryptionConfig({ "paths": { ".*": { "toEncrypt": {"owner": "encryptedOwner"}, "toDecrypt": { "encryptedOwner.encryptedData": "owner", "adoption.encryptedOwner.encryptedData": "adoption.owner" } } }, "encryptionCertificate": "./path/to/encryptionCertificate.pem", "decryptionKey": "./path/to/decryptionKey.pem" }) # Used for employees and payment endpoints def build_full_body_encryption_config(): return JweEncryptionConfig({ "paths": { ".*": { "toEncrypt": {"$": "$"}, "toDecrypt": {"$": "$"} } }, "encryptionCertificate": "./path/to/encryptionCertificate.pem", "decryptionKey": "./path/to/decryptionKey.pem" }) encryption_config_for_adoptions = build_encryption_config_for_adoptions() full_body_encryption_config = build_full_body_encryption_config() ``` ```go import "github.com/mastercard/client-encryption-go/jwe" import "github.com/mastercard/client-encryption-go/utils" // Load certs and keys encryptionCertificate, _ := utils.LoadEncryptionCertificate("./path/to/encryptionCertificate.pem") decryptionKey, _ := utils.LoadDecryptionKey("./path/to/decryptionKey.pem", "password") // Used for adoption endpoints cbAdoptions := jwe.NewJWEConfigBuilder() encryptionConfigForAdoptions := cbAdoptions.WithDecryptionKey(decryptionKey). WithCertificate(encryptionCertificate). WithEncryptionPath("$.owner", "$.encryptedOwner"). WithDecryptionPath("$.encryptedOwner.encryptedData", "$.owner"). WithDecryptionPath("$.adoption.encryptedOwner.encryptedData", "$.adoption.owner"). Build() // Used for employees and payment endpoints cbFullBody := jwe.NewJWEConfigBuilder() fullBodyEncryptionConfig := cbFullBody.WithDecryptionKey(decryptionKey). WithCertificate(encryptionCertificate). WithEncryptionPath("$", "$"). WithDecryptionPath("$", "$"). Build() ```
Configure your client using our client libraries. These libraries are available in several languages, and we recommend that you utilize these libraries to encrypt the sensitive data used by this service. | | ![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 different `README.md` files for detailed how-to information. ### Correlation ID {#correlation-id} The correlation ID is a unique identifier assigned to each API request and is propagated across all downstream systems for traceability. How to retrieve it: 1. Make your REST API call as usual 2. Inspect the HTTP response headers 3. Look for header X-Correlation-Id **Example:** ```text Plain Text HTTP/1.1 200 OK Content-Type: application/json X-Correlation-Id: 0.b6f2717.1776750106.19f2f20f ``` This value can then be used when engaging Mastercard support or for logging/tracking correlation across systems. ## Environments {#environments} | **Environment** | **Base URL** | **Auth \& Encryption** | **Description** | |-----------------|---------------------------------------------------------------|------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Sandbox | `https://sandbox.api.mastercard.com/loyalty/benefits/sandbox` | OAuth 1.0a + JWE --- no environment-specific configuration | Early-access environment that validates your OAuth signing 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 keys to authenticate with this environment. The keys are set up when you create your project. To access Sandbox select Benefit Allocation Service when setting up [My Projects](https://developer.mastercard.com/dashboard) | | MTF | `https://sandbox.api.mastercard.com/loyalty/benefits` | OAuth 1.0a + 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 keys for authentication. | | Production | `https://api.mastercard.com/loyalty/benefits` | OAuth 1.0a + JWE --- no environment-specific configuration | In production you can access Benefit Allocation Service. To access production, select [Request Production Access](https://developer.mastercard.com/dashboard) in your Benefit Allocation Service project. | ### 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-allocations-service/documentation/use-cases/index.md) section to learn how to access the API and generate your credentials.