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

## Client Authentication {#client-authentication}

Warning: **Key Expiry:** Confirmed Fraud API client keys will expire after 30 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. |

You must sign every request you send to Mastercard via 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.
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.

### Mastercard Encryption {#mastercard-encryption}

Mastercard encryption is a custom way of representing encrypted content in JSON format which supports both field level encryption and entire payload encryption.


Mastercard encryption uses AES in [CBC](https://en.wikipedia.org/wiki/Block_cipher_mode_of_operation#Cipher_Block_Chaining_(CBC))(Cipher Block Chaining) mode with [PKCS#7 padding](https://datatracker.ietf.org/doc/html/rfc5652#section-6.3) and RSA with [OAEP](https://en.wikipedia.org/wiki/Optimal_asymmetric_encryption_padding) (Optimal Asymmetric Encryption Padding).
Tip: Do you want to learn more about the encryption scheme Mastercard uses? If so, visit our [Mastercard Encryption Guide](https://developer.mastercard.com/platform/documentation/security-and-authentication/securing-sensitive-data-using-payload-encryption/#mastercard-encryption).

#### Mastercard Encryption code {#mastercard-encryption-code}

    FieldLevelEncryptionConfig config = null;
    try {
        config = FieldLevelEncryptionConfigBuilder.aFieldLevelEncryptionConfig()
            .withEncryptionCertificate(getEncryptionCertificate(encryptioncert))
            .withEncryptionPath("$", "$")
            .withOaepPaddingDigestAlgorithm("SHA-256")
            .withEncryptedValueFieldName("encryptedValue")
            .withEncryptedKeyFieldName("encryptedKey")
            .withIvFieldName("iv")
            .withEncryptionKeyFingerprint(fingerprint)
            .withEncryptionKeyFingerprintFieldName("publicKeyFingerprint")
            .withOaepPaddingDigestAlgorithmFieldName("oaepPaddingDigestAlgorithm")
            .withFieldValueEncoding(FieldValueEncoding.HEX)
            .build();
    } catch (EncryptionException | IOException | CertificateException ex) {
        throw new EncryptionException("Error occurred while creating FieldLevelEncryptionConfig for encryption", ex);
    }

### 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 Confirmed Fraud API:

| **Environment** |                                                                         **Description**                                                                          |
|-----------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Sandbox         | Pre-production test environment containing the latest pre-release version of the real APIs, intended for full integration testing prior to moving to production. |
| Production      | Full production environment containing the latest production API release.                                                                                        |

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