# API Basics
source: https://developer.mastercard.com/open-finance-us/documentation/onboarding/index.md

## Environments {#environments}

Open Finance provides Sandbox and Production environments.

### Sandbox {#sandbox}

The Sandbox environment is designed for development and testing using mock data. A Sandbox project gives you access to the Open Finance Test Drive plan. Test Drive is a non-billable, unlimited plan that provides access to all Open Finance API endpoints.

To set up a Sandbox project and start using the APIs, follow the [Quick Start Guide](https://developer.mastercard.com/open-finance-us/documentation/quick-start-guide/index.md).

The Sandbox environment includes a variety of test institutions that you can use for testing. These institutions simulate different banking scenarios that might be useful for your development and testing processes. For more information on test data, see [Test Profiles](https://developer.mastercard.com/open-finance-us/documentation/integration-and-testing/test-the-apis/index.md).

### Production {#production}

Once you've thoroughly tested your application in the Sandbox environment and are confident that it's working as expected, you can request an upgrade to Production.

See [Moving to Production](https://developer.mastercard.com/open-finance-us/documentation/onboarding/index.md#moving-to-production) for details.

## Authentication {#authentication}

To use the Open Finance REST APIs, you will need the following:

* **Partner ID** - The Partner ID is a unique identifier for a specific set of credentials, including the secret and appKey. All requests sent to Mastercard Open Finance must include a token for accessing Open Finance APIs. To create a token, you are required to provide the PartnerID along with the corresponding secret and appKey.

* **Secret** and **App Key** - Credentials required to authenticate your API calls.

Tip: Your Production and Sandbox environments have different Partner IDs. You can also create multiple Partner IDs within an environment for different use. Make sure you are using the correct Partner ID.

To get the credentials for a project, select it in the [Dashboard](https://developer.mastercard.com/dashboard) then select **Credentials** at left.

![](https://static.developer.mastercard.com/content/open-finance-us/uploads/sandboxcreds.png)

All requests sent to Mastercard Open Finance must include a `Finicity-App-Token` HTTP header. Use your Partner ID and Secret with the following endpoint whenever you need to generate a new access token:

API Reference: `POST /aggregation/v2/partners/authentication`

Note: Access tokens are valid for two hours. As a best practice, generate a new token when the current token is older than 90 minutes to avoid expiration during API calls.
* Command:

```sh
curl --location --request POST 'https://api.finicity.com/aggregation/v2/partners/authentication' \
--header 'Content-Type: application/json' \
--header 'Finicity-App-Key: {{appKey}}' \
--header 'Accept: application/json' \
--data-raw '{
    "partnerId": "{{partnerId}}",
    "partnerSecret": "{{partnerSecret}}"
}'
```

* Expected response:

```json
{
  "token": "YBh22Sb9Es6e66Q7lWdt"
}
```

### Troubleshooting {#troubleshooting}

#### "Too Many Requests" Error {#too-many-requests-error}

If you receive a "too many requests" error, this may indicate that the App Key is incorrect. The error occurs because the App Key controls the rate limit, and invalid keys have a rate limit of 0.

If the Partner ID or Partner Secret is wrong, you will receive an "Invalid Credentials" error instead.

#### Account Lockout After Failed Authentication {#account-lockout-after-failed-authentication}

After 5 attempts to call **Create Access Token** with an incorrect Secret, API access for the Partner ID used will be locked. You will receive a 24302 error for all subsequent API calls.

Contact [Open Finance support](https://developer.mastercard.com/open-finance-us/documentation/support/index.md#create-a-support-case-in-scm) to get assistance unlocking your account.

### Delete Partner ID {#delete-partner-id}

To delete a Partner ID and the associated Secret and App Key, select **Delete credential** from the pulldown menu at right.

![](https://static.developer.mastercard.com/content/open-finance-us/uploads/delete-ucd-credential.png)

Once you delete the credentials, you can no longer use them to access the APIs. When deleting a set of credentials, ensure there's another set of active credentials.

### Modify Partner Secret {#modify-partner-secret}

To rotate your secret, call the Modify Partner Secret endpoint. Keep in mind that you will need to update your integration with the new API secret to ensure your app continues to process requests successfully.
Note: Your partner (API) secret does not expire, however, to maintain the security of your API account, we recommend that you rotate (update) your API secret at least once every 12 months.
API Reference: `PUT /aggregation/v2/partners/authentication`

### OBWMS Authentication {#obwms-authentication}

To use the [Open Banking Webhook Management System (OBWMS)](https://developer.mastercard.com/open-finance-us/documentation/webhooks/obwms/index.md), you will also need to add and download a **Mastercard signature verification key** from your project dashboard.

![](https://static.developer.mastercard.com/content/open-finance-us/uploads/create-sig-key-obwms.png)
Tip: Not all services within Mastercard US Open Finance use the OBWMS system for webhooks. Open Finance services and products are being migrated to the new webhook management system gradually. The documentation will indicate where OBWMS is used and how to verify the webhooks in each case.

See [Webhook Notifications](https://developer.mastercard.com/open-finance-us/documentation/webhooks/index.md) for more information and a list of which services use their own webhook notifications or OBWMS.

## Moving to Production {#moving-to-production}

To request Production access, click the **Request Production access** button on the Summary page.

When you request an upgrade to the Production environment, you can choose to request a **Test Drive Premium (non-billable)** plan or a **Production (billable)** plan.
Note: Access to these plans will only be approved if a contract between you and Mastercard has been executed. Work with your Sales Representative or Client Success Manager to upgrade to Production. Contact [OFin.contactsales@mastercard.com](mailto:OFin.contactsales@mastercard.com) for more information.

### Test Drive Premium Plan {#test-drive-premium-plan}

Test Drive Premium is a free, 30-day limited-duration plan that grants you access to all Open Finance API endpoints. After the 30-day period, you will automatically be transitioned to the Production (billable) plan. This plan allows you to test your integration with live financial data before fully moving to the Production plan.

### Production (Billable) Plan {#production-billable-plan}

This is a billable plan that provides access to the Open Finance API endpoints specified in your contract with Mastercard, limiting data retrieval to those endpoints only. API calls made on this plan are subject to billing based on the terms of your agreement with Mastercard. This plan should not be used for testing purposes.

After you select a suitable plan and click **Proceed**, the credentials required to access the API in the Production environment are created. Make a note of the Partner ID and share it with your Mastercard Representative. These credentials will only be active and ready to use in Production after Mastercard reviews and approves your Production access request.

### Additional Production Credentials {#additional-production-credentials}

You can also request additional Production credentials using the **Add Partner ID** button.

## View API Usage {#view-api-usage}

Click **Usage** (at left, under **Details**) to gain valuable insights into the usage of the API and traffic for each endpoint specific to a Partner ID.

![](https://static.developer.mastercard.com/content/open-finance-us/uploads/mcd-usage.png)

## Access Client Hub {#access-client-hub}

The Client Hub provides a web-based interface to manage some key Open Finance
operations. You can use it to:

* check financial institution status
* view Lend report history
* customize Data Connect
* order Lend reports without using the API

<br />

Click **Access Client Hub** from the pulldown menu at the right of the credentials panel to go to the Client Hub.

![](https://static.developer.mastercard.com/content/open-finance-us/uploads/select-mcd-hub.png)

For more information, see [Client Hub Guide](https://developer.mastercard.com/open-finance-us/documentation/client-hub-guide/index.md).

## Edit Project Details {#edit-project-details}

To edit project details, click **Settings** (at left, under **Manage**).

You can update the following details in a project:

* Project's name
* Details of the company on behalf of which the project is created
* You can update the client company details for an Open Finance project created on behalf of a client. However, you cannot change an Open Finance project created for yourself into one created for a client, or vice versa.

## Team Management {#team-management}

You can invite team members to your Open Finance project to ensure that all the members are notified of the project activities. You must be an *Admin (Owner)* to add or remove a team member in the project. To learn more about how you can use the Team Management feature, see the [Team Management](https://developer.mastercard.com/platform/documentation/managing-your-account/team-management/) section of our [Mastercard Developers Platform](https://developer.mastercard.com/platform/documentation/) documentation.

## See Also {#see-also}

[Quick Start Guide](https://developer.mastercard.com/open-finance-us/documentation/quick-start-guide/index.md)