# 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 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
Mastercard 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 Allocations Service API client {#generating-your-own-benefit-allocations-service-api-client}
Create customizable API clients from the Benefit Allocations 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 Allocations 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.
| |  |  |  |  |
|----------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **Download/install** | [](https://central.sonatype.com/artifact/com.mastercard.developer/client-encryption) | [](https://www.nuget.org/packages/Mastercard.Developer.ClientEncryption.Core/) | [](https://pypi.org/project/mastercard-client-encryption/) | [](https://www.npmjs.com/package/mastercard-client-encryption) |
| **View on GitHub** | [](https://github.com/Mastercard/client-encryption-java) | [](https://github.com/Mastercard/client-encryption-csharp) | [](https://github.com/Mastercard/client-encryption-python) | [](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 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. |
### 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.