# Data retention controls

Belvo offers mechanisms to let you control the data that is retained regarding your users. These mechanisms are divided into two levels:

- Link level
- Resource level


## Link-level data retention controls

When creating a link, you can set parameters that define how Belvo stores:

- Encrypted credentials (`credentials_storage`)
- User-derived data (`stale_in`)


### `credentials_storage`

The `credentials_storage` parameter controls how long Belvo will store the encrypted credentials in our database. You can set the following values:

| Value | Description | Link type |
|  --- | --- | --- |
| `store` | Belvo will store the encrypted credentials associated with the user until the link is deleted. For recurrent links, this must be set to `store`. | Single and recurrent |
| `nostore` | Belvo will not store encrypted credentials for the user unless an MFA token is required. If an MFA token is required, we store the credentials for a maximum of 15 minutes, calculated from the time the link was created (the `created_at` timestamp), after which the credentials are deleted from our system. **Note**: You must indicate which resources you want to retrieve information for in `fetch_resources` when you set this parameter to `nostore`. You will not be able to retrieve any information using POST calls about the link. | Single |
| `1d - 365d` | Belvo stores the encrypted credentials for the period indicated by you (minimum 1 day, maximum 365 days), calculated from the link’s `created_at` timestamp. After this period, you will not be able to retrieve any data using POST calls.    For single links, by default this is set to `365d`. | Single |


With `nostore` or `1d-365d`, once the period has expired the link status will change to `invalid`. If you need to retrieve additional information about your user, you will need to ask them to create the link again.

After you create the link you cannot update the values for `credentials_storage`. You will need to delete the link and if necessary ask your user to connect again

### `stale_in`

The `stale_in` parameter controls how long Belvo stores user-derived data. The period is relative to the link’s `last_updated_at` (the last time that the user’s account was accessed) timestamp. You can set the following values:

| Value | Description | Link type |
|  --- | --- | --- |
| `1d - 365d` | Belvo stores the user-derived data for the period indicated by you (minimum 1 day, maximum 365 days). The period is calculated relative to the `link.last_updated_at` timestamp. By default, this is set to `365d`. | Single and recurrent |


`stale_in` only controls the deletion of the data associated with a user. To delete the link, you need use our Delete a link request

## Resource-level data retention controls

### `save_data`

Whenever you make a POST call to retrieve data about a user, you can choose whether or not Belvo stores any user-derived data using the `save_data` parameter. You can set the following values:

| Value | Description | Applies to |
|  --- | --- | --- |
| `true` | The user-derived data is stored in Belvo’s database. The HTTP response will be a `201` created. This is the default value. | All POST calls |
| `false` | No user-derived data is stored in Belvo’s database. The HTTP response will be a `200` Ok. | All POST calls |


## Use cases

### PFMs and ERPs

PFMs and ERPs need recurrent access to information (both current and historical) in order to provide clients with a detailed overview of their accounts, balances, and transactions. For this use case, we recommend using recurrent links with the default data retention controls:


```json
// Default credentials and user-derived data storage
{
    "access_mode": "recurrent",
    "credentials_storage": "store", // Default
    "stale_in": "365d", // Default
}
```

Unless the recurrent link’s status is `invalid` or `token_required`, you will continue to be able to retrieve historical data for over 365 days.

### Recurring credit assessments and short-term loans

With recurring credit assessments or short-term loans, you most likely want to only store data for a limited amount of time so that you can follow your user’s account balances and payments for the duration of the loan. For this case, we recommend using single links where you only store credentials and user-derived data for the duration of the loan:


```json
// Store credentials and data for a limited period
{
    "access_mode": "single",
    "credentials_storage": "100d",
    "stale_in": "100d",
    "fetch_resources": ["ACCOUNTS", "OWNERS", "TRANSACTIONS"]
}
```

All user-derived data will be stored in our database relative to the link’s `last_accessed_at` timestamp. For example, if you create a link on the first day of the month and then make a POST call to retrieve data on the 10th day of the month, we store the user-derived data for 21 days after that day

### Compliance requirements

For companies that are required to undergo routine audits or compliance checks, you might not want to store sensitive data any longer than absolutely necessary. For this case, we recommend using single links with minimal data storage:


```json
// Store only the necessary data for audit or compliance
{
    "access_mode": "single",
    "credentials_storage": "3d",
    "stale_in": "2d",
    "fetch_resources": ["ACCOUNTS", "BALANCES", "TRANSACTIONS"]
}
```

In this case, the credentials will be voided after three days, however, the user-derived data will still be present in Belvo’s system until two days have passed after the link’s `last_updated_at` timestamp

### ID verification or credit assessments

In the case that you want to use Belvo for ID verification or one-off credit assessments, you won’t need to access user-derived data at a later date. For this case, we recommend using single links where you do not store credentials and have a minimal user-derived data storage:


```json
// Do not store credentials or user-derived data
{
    "access_mode": "single",
    "credentials_storage": "nostore",
    "stale_in": "1d",
    "fetch_resources": ["ACCOUNTS", "OWNERS", "TRANSACTIONS"]
}
```

Once the link is created, you need to wait for the `historical_update` webhook for each of the resources you list. You can then retrieve the user-derived data using a GET call.

The user-derived data will be removed from our database one day later

### Can recurrent links have a defined credential storage time range?

For recurrent links, `credentials_storage` must be set to `store`. If you would like to remove the link (and any user-derived data associated with the link), you need to use the Delete a link request.

### How does `stale_in` work for recurrent links?

With recurrent links, once a link `status` is set to `invalid` or `token_required` we are no longer able to access the user’s institution. As such, the link’s `last_accessed_at` timestamp will not be updated and Belvo will delete any user-derived data once the `stale_in` period is met.

### Does Belvo delete user-derived data by default for recurrent links?

In the case that the `last_accessed_at` timestamp has not been updated for 365 days, Belvo will automatically remove any user-derived data relating to the link.

### Can I change the link’s `credentials_storage` or `stale_in` values?

After you create the link you cannot update the values for `credentials_storage` or `stale_in`. You will need to delete the link and ask your user to connect again.

### Can I update a link’s credentials if it is still within the storage period?

Yes, if the storage period has not yet expired, you can update the credentials or provide an MFA token using our Update a link’s credentials request.

If you’re using recurrent links, you’ll receive information that a link needs to be updated via our Links webhooks.

### If I delete a link, does all the associated user-derived data also get deleted?

Yes, once you delete a link, Belvo will remove any data (including credentials) associated with the user.

### Does Belvo store any data when from the Enrich Your Own Data suite of resources?

No, Belvo does not store any data when you use our Enrich Your Data Data resources.

### I forgot to use `save_data: false` when I made a POST call. How do I remove the data from Belvo’s database?

To remove any resource data, just use the resource’s Delete a {resource name} request. For example, if you retrieved account information, you can use the Delete an account request.

### How does Belvo encrypt credentials?

Belvo uses industry-standard AES-256 symmetric encryption to encrypt credentials. We also provide an additional layer of security when you use Belvo’s Connect Widget where we encrypt the user’s credentials first at the widget level using RSA 2048 asymmetric encryption.