# API Security
source: https://developer.mastercard.com/pay-with-rewards/documentation/api-basics/api-security/index.md

### Client Authentication {#client-authentication}

Warning: **Key Expiry:** Mastercard Pay with Rewards Keys will expire after one year. You will have to generate a new set of keys when they expire. To do this, go to your project dashboard and under API Keys select 'Add Key'.

|          Authentication Protocol           |                                                                                                                                Details                                                                                                                                |
|--------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [OAuth 1.0a](https://oauth.net/core/1.0a/) | Mastercard uses OAuth 1.0a with a body hash extension for authenticating the API clients. OAuth 1.0a is an authentication and authorization protocol that guarantees the integrity and authenticity of incoming API calls and allows for non-repudiation of requests. |

OAuth requires every request that you send to Mastercard to be signed with an RSA private key. A private-public RSA key pair must be generated consisting of:

1. A **private key** for the OAuth signature for API requests. It is recommended to keep the private key in a password-protected or hardware keystore. Data encrypted using a public key can only be decrypted using the corresponding private key.
2. A **public key** is shared with Mastercard during the project setup process through either a certificate signing request (CSR) or the API Key Generator. Mastercard will use the public key to verify the OAuth signature that is provided on every API call.

* Requests with a body must be signed using the [Google Request Body Hash](https://datatracker.ietf.org/doc/id/draft-eaton-oauth-bodyhash-00.html) extension for OAuth.
* The OAuth keys for your project can be set up on your project dashboard here ([Developer Dashboard](https://developer.mastercard.com/dashboard)), after you create a project.

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/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 is encrypted by default when transmitted across networks. Mastercard uses end-to-end payload encryption to secure sensitive data such as personal identifiable information (PII).

* Visit [Securing Sensitive Data Using Payload Encryption](https://developer.mastercard.com/platform/documentation/security-and-authentication/securing-sensitive-data-using-payload-encryption/) to learn more about our encryption methods.   

### JWE {#jwe}

JSON Web Encryption (JWE) represents encrypted content using JSON-based data structures [RFC7159](https://datatracker.ietf.org/doc/html/rfc7159) and base64url encoding. Mastercard uses [JWE compact serialization](https://datatracker.ietf.org/doc/html/rfc7516#section-7.1) for the encryption of sensitive data and supports both field level encryption and entire payload encryption.

* Visit our [JWE Encryption Guide](https://developer.mastercard.com/platform/documentation/security-and-authentication/securing-sensitive-data-using-payload-encryption/#jwe-encryption) to learn more about JWE encryption.

### Encryption Libraries {#encryption-libraries}

Mastercard has abstracted the encryption scheme into our [client encryption libraries](https://developer.mastercard.com/platform/documentation/security-and-authentication/securing-sensitive-data-using-payload-encryption/#client-libraries), which are available in several of the most used development languages. We highly recommend that you utilize these libraries to encrypt the sensitive data used by this service.

## Environments Descriptions {#environments-descriptions}

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

| **Environment** |                                                                                                                                                                          **Description**                                                                                                                                                                           |
|-----------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Sandbox         | The sandbox environment is a pre-production 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. To access Sandbox, select Mastercard Pay with Rewards API when setting up [My Projects](https://developer.mastercard.com/dashboard). |
| Production      | 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 Reference Service project you have setup.                                                                       |

## How to Consume the Pay with Rewards API? {#how-to-consume-the-pay-with-rewards-api}

Note: There are multiple ways of integrating with Pay with Rewards Service:

1. Using a generated API client (recommended)
2. Using a method of your choice

### Generating your API client {#generating-your-api-client}

Create customizable API clients from the Pay with Rewards Service 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/getting-started-with-mastercard-apis/generating-and-configuring-a-mastercard-api-client) tutorial using:

1. The following [mastercard-pay-with-rewards.yaml](https://static.developer.mastercard.com/content/pay-with-rewards/swagger/mastercard-pay-with-rewards.yaml) (49KB).
2. An Open Banking 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 mastercard-pay-with-rewards.yaml -o api_client
   ```

3. The following payload encryption code configurations:
   * Java

   ```java
       @Bean
       public EncryptionConfig fullBodyEncryptionConfig() throws EncryptionException, GeneralSecurityException, IOException {
           Certificate encryptionCertificate = EncryptionUtils.loadEncryptionCertificate(encryptionCertificateFilePath);
           PrivateKey decryptionKey = EncryptionUtils.loadDecryptionKey(decryptionKeyFilePath, decryptionKeyAlias, decryptionKeyPassword);

           return JweConfigBuilder.aJweEncryptionConfig()
                   .withEncryptionCertificate(encryptionCertificate)
                   .withEncryptionPath("$", "$")
                   .withDecryptionKey(decryptionKey)
                   .build();
       }

   ```

### Using a method of your choice {#using-a-method-of-your-choice}

Pay with Rewards exposes a REST API: you are free to use the REST/HTTP client of your choice and can still leverage the Mastercard open-source [client authentication](https://developer.mastercard.com/platform/documentation/authentication/using-oauth-1a-to-access-mastercard-apis/#client-libraries) and [client encryption](https://developer.mastercard.com/platform/documentation/security-and-authentication/securing-sensitive-data-using-payload-encryption/) libraries for signing your requests and dealing with payload encryption.

For that, please refer to the Pay with Rewards Service [REST API Reference](https://developer.mastercard.com/pay-with-rewards/documentation/api-reference/index.md).

## Next Steps {#next-steps}

Now that you have an understanding of the services authentication and encryption, proceed to the [Quick Start Guide](https://developer.mastercard.com/pay-with-rewards/documentation/quick-start-guide/index.md) section to learn how to access the API and generate your credentials.