# API Basics
source: https://developer.mastercard.com/digital-redemptions/documentation/api-basics/index.md

## API Security {#api-security}

### Client authentication {#client-authentication}

Warning: **Key Expiry:** Mastercard Digital Redemptions 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.

|      Authentication Protocol      |                                                                                                                                      Details                                                                                                                                      |
|-----------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [OAuth 2.0](https://oauth.net/2/) | Mastercard uses [OAuth 2.0 Authorization](https://datatracker.ietf.org/doc/html/rfc6749) with the [Client Credentials Grant](https://datatracker.ietf.org/doc/html/rfc6749#section-4.4), using the FAPI 2.0 security profile (strong client authentication + DPoP token binding). |

OAuth 2.0 (client credentials) requires your application to request an access token from the authorization server, and call APIs using that access token with DPoP token binding.

Your application needs two sets of key material:

1. An **authentication private key** (from Mastercard Developers) used to sign the client assertion (`private_key_jwt`) for token requests.

2. A **DPoP key pair** generated and stored by your application, used to sign DPoP proofs (per token request and per API call).

* Token requests include a signed client assertion (`private_key_jwt`) and a DPoP proof.
* API calls send `Authorization: DPoP <access_token>` and a fresh DPoP proof per request (including `htm/htu` and `ath`).
* Nonce handling: if you receive `use_dpop_nonce`, retry with the `DPoP-Nonce` value as the `nonce` claim in the next DPoP proof.

Tip: Do you want to learn more about the authentication scheme Mastercard uses? For implementation details and examples, read our [Using OAuth 2.0 to Access Mastercard APIs](https://developer.mastercard.com/platform/documentation/authentication/using-oauth-2-to-access-mastercard-apis/) guide. Note: **Dual Authentication Support**

Mastercard Digital Redemptions APIs support both OAuth 1.0a and OAuth 2.0 at the project level. A project can be configured to use either protocol individually, or both simultaneously, with no preference or migration requirement implied between them.

### 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/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 Digital Redemptions 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 Digital Redemptions API? {#how-to-consume-the-digital-redemptions-api}

Note: There are multiple ways of integrating with Digital Redemptions Service:

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

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

Create customizable API clients from the Digital Redemptions 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 [merchandise-digital-redemptions.yaml](https://static.developer.mastercard.com/content/digital-redemptions/swagger/merchandise-digital-redemptions.yaml) (66KB).
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 merchandise-digital-redemptions.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}

Digital Redemptions 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/authentication/securing-sensitive-data-using-payload-encryption/#client-libraries) libraries for signing your requests and dealing with payload encryption.

For that, please refer to the Digital Redemptions Service [REST API Reference](https://developer.mastercard.com/digital-redemptions/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/digital-redemptions/documentation/quick-start-guide/index.md) section to learn how to access the API and generate your credentials.