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

## Client Authentication {#client-authentication}

👉 Let the user know what type of authentication your service uses inside a table. See the templates for OAuth 1.0a, OAuth 2 and mTLS below:   

|          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. The private key is used to encrypt the signature base string hash, and is decrypted using the public key at the server.   
2. A **public key** is shared with Mastercard during the project setup process through either a certificate signing request (CSR) or an 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 are created during the process of project creation on Mastercard Developers. Additionally, you can add new OAuth keys inside your project dashboard if needed.

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/core/1.0a/) | Mastercard uses [OAuth 2.0 Authorization](https://datatracker.ietf.org/doc/html/rfc6749#page-1) framework with [Client Credentials Grant](https://datatracker.ietf.org/doc/html/rfc6749#section-4.4). In this flow, the Integrator needs to authenticate towards the Authorization Server to gain an Access Token that will be used to access the API. |

OAuth 2.0a requires you to generate an asymmetric cryptography public-private key pair and certificate. When you authenticate on the authorization server,
only you can obtain access tokens for your clientId. Mastercard validates that your requests are signed with a private key (RSA key) that only you have.

Two files are used for this:   

* private.key: The private key used for signing the JWT.   
* public.pem: The public certificate that can be used to verify the JWT.

The public certificate is shared with mastercard, and the oauth2 endpoint is called to obtain the access token.
A JWT is generated to populate the `client_assertion` filed, this is signed and transmitted between the two parties.
Once the JWT token is signed, the authentication service gets called. This authentication is required to obtain the access token required to access the API.
Once the access token is obtained, it is added to the API request, inside the authorization (bearer) header.

|                Authentication Protocol                |                                                                                                   Details                                                                                                   |
|-------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [mTLS](https://datatracker.ietf.org/doc/html/rfc5246) | Mastercard APIs using mTLS authentication require two-way TLS certificate exchange between the API Client and Mastercard Server. It uses digital certificates signed using PKI to authenticate API clients. |

MTLS is a mutual TLS handshake protocol to establish a secure connection between client and server. In mTLS authentication, your client application sends a request for a protected resource to Mastercard server. The Mastercard server then presents a 'server certificate' back to the client which the client verifies.
Your application then presents a corresponding 'client certificate' back to Mastercard who verifies the cert. A client key exchange and change cipher spec takes place and Mastercard returns the protected resource in response.

There are two different types of mTLS client certificates, depending on the stage of your project:

1. Sandbox mTLS certificates, which give access to an API sandbox that mimics a live Production environment (\*mtf.services.mastercard.com)   
2. Production mTLS certificates, which allow an application to access the Production environment (\*services.mastercard.com)

\*Domain/Server URL may vary depending on the API. Please check the API Reference section of the service documentation for the correct Server URL.
Tip: Do you want to learn more about the mTLS authentication scheme Mastercard uses? For that, read our [Using mTLS to Access Mastercard APIs](https://developer.mastercard.com/platform/documentation/authentication/using-mtls-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 secured by default when transmitted across networks. However, Mastercard additionally uses end-to-end payload encryption to encrypt sensitive data such as personal identifiable information (PII).
Note: 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.

👉 Let the user know which type of encryption your service uses. If your service uses JWE use the information below. If your service does not use payload encryption please ignore this.   


### JWE {#jwe}

👉 Use this description of JWE. Full body, payload encryption is recommended by us.   

|                       Authentication Protocol                        |                                                                                                                                                                                           Details                                                                                                                                                                                            |
|----------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [JSON Web Encryption](https://datatracker.ietf.org/doc/html/rfc7516) | 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. |

Note: Visit our [JWE Encryption Guide](https://developer.mastercard.com/platform/documentation/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://github.com/Mastercard?q=client-encryption), which are available in several programming languages. We recommend that you utilize these libraries to encrypt the sensitive data used by this service.

👉 Let the user know which environments your service uses inside a table.   

<br />

## Environment Descriptions {#environment-descriptions}

👉 Describe the environments your service uses.   

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

| Environment |                                                                                                                                                                                                                                     Description                                                                                                                                                                                                                                     |
|-------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Sandbox     | The sandbox environment is an open, self-service 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 '{Your Service API}' when setting up My Projects and create your project keys and ensure you have received appropriate approvals.                                                                                      |
| MTF         | The MTF environment is a pre-production environment with additional onboarding required. Once a customer has a contract where their data is required to be loaded for testing, or they need access to more powerful testing tools, such as payments test harnesses, MTF becomes a more suitable environment. To access MTF environment, you need to reach out to [Customer Implementation Team (CIS)](mailto:example@mastercard.com) and we will get you set up on the environment. |
| 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 `{Mastercard Golden Reference Service API}` project you have setup.                                                                                                                                                              |

## How to Consume the API? {#how-to-consume-the-api}

👉 Let the user know how to generate an API client. Use the content below and if your service uses encryption update the code configurations to match your service.   

### Generating your own {Pet Store} API client {#generating-your-own-pet-store-api-client}

Create customizable API clients from the {Pet Store} 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/security-and-authentication/generating-and-configuring-a-mastercard-api-client/) tutorial using:

👉 Use the [Tabbed Block Short Code](https://stage.developer.mastercard.com/jamstack/documentation/theme/shortcodes/code-block/) here.

1. The following [Pet Store OpenAPI specification file](https://static.developer.mastercard.com/content/mastercard-agent-pay/documentation/api-basics/static/swagger/petstore.yaml).   
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 petstore.yaml -o api_client
   ```

3. The payload encryption Java configurations below:
   * Java

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

     return JweConfigBuilder.aJweEncryptionConfig()
       .withEncryptionCertificate(encryptionCertificate)
       .withDecryptionKey(decryptionKey)
       .withEncryptionPath("$.ssn","$")
       .withDecryptionPath("$.encryptedSsn","$.ssn")
       .withDecryptionPath("$.encryptedFirstName","$.firstName")
       .withDecryptionPath("$.encryptedLastName","$.lastName")
       .withDecryptionPath("$.encryptedPhoneNumber","$.phoneNumber")
       .withDecryptionPath("$.encryptedEmail","$.email")
       .withDecryptionPath("$.encryptedUsername","$.username")
       .build();
   }
   @Bean
   public EncryptionConfig fieldLevelEncryptionConfigForAdoptions() throws EncryptionException, GeneralSecurityException, IOException {
     Certificate encryptionCertificate = EncryptionUtils.loadEncryptionCertificate(encryptionCertificateFilePath);
     PrivateKey decryptionKey = EncryptionUtils.loadDecryptionKey(decryptionKeyFilePath, decryptionKeyAlias, decryptionKeyPassword);

     return JweConfigBuilder.aJweEncryptionConfig()
       .withEncryptionCertificate(encryptionCertificate)
       .withDecryptionKey(decryptionKey)
       .withEncryptionPath("$.owner","$.encryptedOwner")
       .withDecryptionPath("$.encryptedOwner","$.owner")
       .build();
   }
   @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();
   }
   ```

## Next Steps {#next-steps}

👉 Tell the user to proceed to the Quick Start Guide section.   

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