# API Basics
source: https://developer.mastercard.com/fld-suspected-fraud/documentation/api-basics/index.md

## Client Authentication {#client-authentication}

Warning: **Key Expiry**: Mastercard Suspected Fraud Keys will expire after 12 months, 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. |

You must sign every request you send to Mastercard through OAuth using an RSA private key. A private-public RSA key pair consists of the following components:

1. A **private key** for the OAuth signature for API requests. You should 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. 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, 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}

[TLS/SSL](https://en.wikipedia.org/wiki/Transport_Layer_Security) secures the transport between client applications and Mastercard, which means data is encrypted by default when transmitted across networks. Where sensitive data like Personally Identifiable Information (PII) is sent, this is also encrypted using the Mastercard encryption scheme.
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 both field level encryption and entire payload encryption. |

* We use full body JWE encryption in our Adoptions and Employees endpoints.

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).

### 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.

## Environment Descriptions {#environment-descriptions}

The following table describes the different environments that are available for the Suspected Fraud API:

| **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 'SuspectedFraudAPI' when setting up My Projects and create your project keys and ensure you have received appropriate approvals.                                                     |
| MTF             | The MTF environment provides a pre-production setup that requires additional onboarding. When a customer signs a contract that requires loading their data for testing or needs access to more powerful testing tools, such as payments test harnesses, they should use MTF as the more suitable environment. To access the MTF environment, contact [apisupport@mastercard.com](mailto:apisupport@mastercard.com), and our team will set you up. |
| 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 project you have setup.                                                                                                                                                                        |

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

### Generating your own Suspected Fraud API client {#generating-your-own-suspected-fraud-api-client}

Create customizable API clients from the Suspected Fraud 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, 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:

1. The following Suspected Fraud API specification file:
   [suspected_fraud_api.yaml](https://static.developer.mastercard.com/content/fld-suspected-fraud/swagger/suspected_fraud_api.yaml) (48KB)

2. Download the reference app, refer [Reference Application](https://developer.mastercard.com/fld-suspected-fraud/documentation/reference-app/index.md) and follow the instructions mentioned in **README.md** file.

3. The following payload encryption code configurations:

   * Java

   ```Java
   public static JweConfig encryptionJweConfig(String encryptioncert) throws EncryptionException {
       JweConfig config = null;
       try {
           config = JweConfigBuilder.aJweEncryptionConfig()
                   .withEncryptionCertificate(getEncryptionCertificate(encryptioncert))
                   .withEncryptionPath("$", "$")
                   .withEncryptedValueFieldName("encryptedValue")
                   .build();
       }catch (EncryptionException | IOException | CertificateException e) {
           throw new EncryptionException("Error occured while creating JweConfig for encryption", e);
       }
       return config;
   }
   ```

   <br />

4. After the successful setup, you will be able to test the Suspected Fraud API.

## 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/fld-suspected-fraud/documentation/quick-start-guide/index.md) section to learn about the different use cases of the service.