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

## Authentication {#authentication}

RiskRecon uses OAuth 2.0 to authenticate and authorize API calls that you make. OAuth 2.0 is an authorization protocol that approves interactions between various entities required to make API calls. To make RiskRecon API calls, from either the sandbox or the production environment, you have to authenticate using a JSON Web Token (JWT).

### Actors in a RiskRecon API Flow {#actors-in-a-riskrecon-api-flow}

A RiskRecon API request passes several stages of authentication and authorization through the following actors to produce the API response:

|            Actors            |                                                                                Description                                                                                |
|------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| API User                     | The entity that initiates the API request.                                                                                                                                |
| HTTP Client                  | The HTTP Client for RiskRecon APIs could be applications such as Postman, Curl, or any HTTP Client in the developer's language of choice.                                 |
| RiskRecon Web Server         | The web server is responsible for handling the initial SSL/TLS handshake with the HTTP Client.                                                                            |
| RiskRecon Application Server | The application server is responsible for handling the business logic and processing user requests. It also handles OAuth 2.0 authorization to validate the bearer token. |
| Load Balancer                | The Load Balancer sits in between the web server and the application server. It is responsible for handling requests between the web server and the application server.   |
| RiskRecon Database           | The RiskRecon database hosts the data.                                                                                                                                    |

### RiskRecon API Authentication and Authorization Flow {#riskrecon-api-authentication-and-authorization-flow}

RiskRecon incorporates the authentication and authorization of its APIs as defined in [OAuth2.0 RFC 6749, section 1.4](https://datatracker.ietf.org/doc/html/rfc6749#section-1.4).

1. The API user makes an API call through an HTTPs client providing the JWT in the API request header.
2. The HTTPs client sends encrypted data over TLS to the web server.
3. The web server forwards the encrypted request to the load balancer.
4. The load balancer forwards the request to the application server over TLS to maintain end-to-end encryption with TLS termination occurring at the load balancer.
5. The application server validates the JWT using OAuth 2.0 authorization and public or private keys:   
   a. The user gets an unauthorized response if the token is invalid, expired, or the header is not present.  
   b. If the user is authenticated, the response is retrieved using the applicable business logic.
6. The application server sends the encrypted response back to the load balancer over TLS.
7. The load balancer forwards the encrypted response to the web server.
8. The web server sends the encrypted response to the HTTPs client.
9. The HTTPs client decrypts the response for the API User.

![](https://static.developer.mastercard.com/content/riskrecon-api/uploads/api-basics-oauth-authorization3.png)

## Encryption {#encryption}

RiskRecon APIs communicate with HTTPs to ensure that the authorization code and data transmitted across networks are encrypted.

Encryption and decryption are handled via HTTPs by the web server and the HTTPs client. The transport between user or client applications and RiskRecon is secured using [TLS/SSL](https://en.wikipedia.org/wiki/Transport_Layer_Security), which uses the RSA asymmetric encryption.

## Key Management {#key-management}

You can create JSON Web tokens for a maximum period of one year. Since the tokens are long-lived access tokens, no refresh tokens are required to authenticate and authorize API requests.

## Environments {#environments}

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

| **Environment** |                                                                                                                                                                                                                                                         **Description**                                                                                                                                                                                                                                                          |
|-----------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Sandbox         | The RiskRecon Sandbox is a simulated production environment that comes with a separate and generated data meant only for testing the APIs and know how they function. You can experiment on various API functionalities, such as action plans, portfolio, breach events, analysis, and findings. The sandbox behaves like the production environment without providing the ability to add, delete, or modify the sandbox portfolio or data. It does not allow you to create data to test and move to the production environment. |
| Production      | The RiskRecon Production environment contains the latest production API release. This environment will be created for you when you are onboarded and provides access to your portfolio and other continuous risk management data.                                                                                                                                                                                                                                                                                                |

### Generating your own RiskRecon API client {#generating-your-own-riskrecon-api-client}

You can create a RiskRecon API Client using any language of your choice. For more details on how to generate a RiskRecon API Client, proceed to the [Tutorials and Guides](https://developer.mastercard.com/riskrecon-api/documentation/tutorials-and-guides/index.md) section.