# 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**                                                                                                                                                                                            |
|-----------------|-----------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Sandbox         | `https://mtf.api.mastercard.co.in/iodr` | 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 Mastercard OAuth 1.0a when setting up My Projects and create your project keys and ensure that you have received appropriate approvals. |
| 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 Sandbox 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.