# API Basics
source: https://developer.mastercard.com/india-online-dispute-resolution/documentation/api-basics/index.md

## Client Authorization {#client-authorization}

Warning: **Key Expiry**: Mastercard IODR keys will expire after 365 days, 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 consists of:

1. A **private key** for the OAuth signature for API requests. Keep the private key in a password-protected or hardware keystore. The private key encrypts the signature base string hash and the server decrypts it using the public key.

2. Share a **public key** with Mastercard during project setup using either a Certificate Signing Request (CSR) or an API Key Generator. Mastercard uses the public key to verify the OAuth signature provided on every API call.

* Sign requests with a body 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 more information, 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}

All connections to Mastercard are secured using [TLS/SSL](https://en.wikipedia.org/wiki/Transport_Layer_Security). Data is secured by default when transmitted across networks. However, Mastercard additionally uses end-to-end payload encryption for sensitive data such as personally 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.

### JWE {#jwe}

|                       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 full body payload encryption. |

Tip: Do you want to learn more about the encryption scheme Mastercard uses? If so, visit our [JWE Encryption Guide](https://developer.mastercard.com/platform/documentation/authentication/securing-sensitive-data-using-payload-encryption/#jwe-encryption).

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

Note: There are multiple ways of integrating with IODR API:

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

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

Create customizable API clients from the IODR API specification and let Mastercard open-source client libraries handle the authentication for you. This approach offers more flexibility and is recommended.

To generate IODR API client, 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/) using:

1. The following IODR API specification file:
   [IndiaOnlineDisputeResolution.yaml](https://static.developer.mastercard.com/content/india-online-dispute-resolution/swagger/IndiaOnlineDisputeResolution.yaml) (43KB)

2. 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 india-online-dispute-resolution.yaml -o api_client
```

3. The following payload encryption code configurations:

* Java
* C#

```java
Certificate encryptionCertificate = EncryptionUtils.loadEncryptionCertificate(encryptionCertPath);
PrivateKey key = EncryptionUtils.loadDecryptionKey(keyFile, keyAlias, password);
JweConfig config = JweConfigBuilder.aJweEncryptionConfig().withEncryptionCertificate(encryptionCertificate)
                    .withEncryptionPath("$", "$").withEncryptedValueFieldName("encryptedValue")
                    .withDecryptionKey(key).withDecryptionPath("$.encryptedValue", "$")
                    .build();
```

```csharp
Certificate encryptionCertificate = EncryptionUtils.LoadEncryptionCertificate(encryptionCertPath);
PrivateKey key = EncryptionUtils.LoadDecryptionKey(keyFile, keyAlias, password);
JweConfig config = JweConfigBuilder.aJweEncryptionConfig().WithEncryptionCertificate(encryptionCertificate)
                    .WithEncryptionPath("$", "$").withEncryptedValueFieldName("encryptedValue")
                    .WithDecryptionKey(key).withDecryptionPath("$.encryptedValue", "$")
                    .Build();
```

4. Configure your client using our [client libraries](https://developer.mastercard.com/platform/documentation/security-and-authentication/securing-sensitive-data-using-payload-encryption/#client-libraries), which are available in several languages. We recommend that you utilize these libraries to encrypt the sensitive data used by this service.

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

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

For more information, refer to the [API Reference](https://developer.mastercard.com/india-online-dispute-resolution/documentation/api-reference/index.md).

## Environment Descriptions {#environment-descriptions}

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

| **Environment** |              **Base URL**               |                                                                                                                                               **Description**                                                                                                                                                |
|-----------------|-----------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| MTF             | `https://mtf.api.mastercard.co.in/iodr` | 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. |
| Production      | `https://api.mastercard.co.in/iodr`     | The production environment is the live environment setting where the API interacts with actual users and the data environment.                                                                                                                                                                               |

Note: **Environment-specific auth/encryption:** OAuth 1.0a authentication and JWE payload encryption are identical across MTF and Production. The only difference is the base URL and requiring no additional steps for promotion.

## Next Steps {#next-steps}

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