---
updatedAt: 2025-09-08T21:26:35.000Z
agentTools:
projectIndex: https://docs.rainforestpay.com/llms.txt
---
# API keys
Create API keys to grant permissions to the Rainforest API
An API key is a long-lived credential that authorizes servers to communicate with the Rainforest API. API keys will generally have broad permissions to access most resources. **API keys should never be sent to the front-end, or otherwise transmitted to the user's browser.**
# Defining a statement
***
A **statement** consists of a set of **permissions** and **constraints** that defines what **resources** and **actions** this session can access.
## What is a resource?
A **resource** is an object in the Rainforest API (e.g. payins, refunds, chargebacks, merchants, etc.).
### Valid resources
| Resource | Description |
| :---------------------- | :--------------------- |
| `api_key` | API key |
| `billing_profile` | Billing profile |
| `chargeback` | Chargeback |
| `deposit` | Deposit |
| `deposit_method` | Deposit method |
| `deposit_method_config` | Deposit method config |
| `device_registration` | Device registration |
| `http_request` | HTTP request |
| `mcc` | Merchant commerce code |
| `merchant` | Merchant |
| `merchant_application` | Merchant application |
| `payin` | Payin |
| `payin_config` | Payin config |
| `payment_method` | Payment method |
| `payment_method_config` | Payment method config |
| `plaid_link` | Plaid link |
| `platform` | Platform |
| `refund` | Refund |
| `routing_number` | Routing number |
| `session` | Session |
| `threeds_attempt` | 3DS attempt |
| `user` | User |
## What is an action?
An **action** is a specific operation on a resource in the Rainforest API.
### Valid actions
| Action | Description |
| :------- | :------------------------------------------------------------- |
| `create` | Create a new resource (e.g, creating a payin\_config or payin) |
| `update` | Update a resource (e.g. updating a merchant\_application) |
| `read` | Read a resource (e.g. reading a payin\_config) |
| `delete` | Delete a resource (e.g. deleting a session) |
## What is a permission?
A **permission** is the combination of a **resource** and an **action** in the format `resource:action`, which determines a specific capability on the Rainforest API (e.g. `payin:create`).
Most API keys and sessions will include multiple **permissions** in order to facilitate more complex API interactions. While these can be enumerated explicitly, you can use a **group**.
## What is a group?
A **group** is a collection of **permissions**. These groups are defined by Rainforest, and will define a collection of permissions needed to integrate with Rainforest Components.
Groups enable you to:
* Simplify and better understand your permissions.
* Allows Rainforest to introduce new features in the Rainforest Components and if they require new resources or actions, then your users will automatically be able to take advantage of them without you needing to update your integration code.
### Valid groups
| Group | Capabilities |
| :---------------------------------------------- | :------------------------------------------------------------------------------------------------------- |
| `group#all` | Gives full access to all actions on Rainforest resources. |
| `group#ach_return_details_component` | See ACH return details. |
| `group#chargeback_details_component` | See chargeback details. |
| `group#deposit_details_component` | See details of a given deposit and open payin, refund, ACH return, and chargeback details. |
| `group#deposit_details_component.create_refund` | Create a refund on the payin details from within the deposit details component. |
| `group#deposit_report_component` | See all deposits and deposit details, which includes payins, refunds, ACH return and chargeback details. |
| `group#deposit_report_component.create_refund` | Create a refund on the payin details from within the deposit report component. |
| `group#merchant_onboarding_component` | Update and submit a merchant application in the merchant onboarding component. |
| `group#payin_details_component` | See payin details in the payin details component. |
| `group#payin_details_component.create_refund` | Create a refund in the payin details component. |
| `group#payin_receipt_component` | See payin details in the payin receipt component. |
| `group#payment_component` | Create a payin or payment method from the payment component. |
| `group#payment_report_component` | See ACH return, chargeback, payin, and refund details within the payment report component. |
| `group#payment_report_component.create_refund` | Create a refund on the payin details page within the payment report component. |
| `group#refund_details_component` | See payin and refund details within the refund details component. |
## What is a constraint?
A **constraint** restricts what actions are allowed based on the specific context of a **resource**. For example, constraints can be used to limit credentials to a specific merchant and might look like the following:
```json
"merchant": {
"merchant_id": "mid_123"
}
```
This will only allow the API key to perform actions on resources whose merchant has the merchant\_id of `mid_123`. If a resource does not have a parent merchant (e.g. a platform, or a merchant itself), this will be skipped.
Any field returned by the API for a given **resource** Get by ID endpoint can be used in a **constraint**, including metadata.
## What is a statement?
A statement is a set of **permissions** and **constraints** that must be met in order to complete the API interaction. An API key is composed of multiple **statements**. While most API keys will only need a single statement, if multiple statements are specified, ***only one*** statement needs to match for the action to be allowed. Statements are **OR**'d together.
Here is an example of creating an API key that is authorized to perform all **actions** on all **resources**, unless that resource has a parent merchant (e.g. payins, payin\_configs, etc). If a parent merchant exists, it must match the provided constraint, meaning it must have a `merchant_id` of `mid_123`. If a parent merchant does not exist, the constraint will be ignored.
```curl
curl --location 'https://api.rainforestpay.com/v1/api_keys' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{api_key}}' \
--data '{
"ttl": 86400,
"statements": [
{
"permissions": ["group#all"],
"constraints": {
"merchant": {
"merchant_id": "mid_123"
}
}
}
]
}'
```
Permissions can also be enumerated explicitly, with more complex constraints. The following is an example of an API key that is authorized to create, read, delete and update payins and nothing else. This constraint requires that the payin have an `internal_id` metadata key with `987654321` as the value.
```curl
curl --location 'https://api.rainforestpay.com/v1/api_keys' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{api_key}}' \
--data '{
"ttl": 86400,
"statements": [
{
"permissions": ["payin:create", "payin:read", "payin:delete", "payin:update"],
"constraints": {
"payin": {
"metadata": {
"internal_id": "987654321"
}
}
}
}
]
}'
```
# API key
***
Once you [create an API key](https://docs.rainforestpay.com/reference/create_api_key), the `api_key` will be enabled and ready for use.
> 🚧 Save the `api_key`
>
> This is the only time you'll be able to access the `api_key` secret. Save it in a safe place. Going forward we will only return a `masked_api_key`.
### Request
```curl request
curl --request POST \
--url 'https://api.rainforestpay.com/v1/api_keys' \
--header 'Authorization: Bearer {{api_key}}' \
--header 'Content-Type: application/json' \
--data-raw '{
"platform_id": "plt_123",
"statements": [
{
"permissions": ["payin:read"],
"constraints": {
"merchant": {
"merchant_id": "mid_123"
},
"payin": {
"metadata": {
"account": {
"id": "123"
}
}
}
}
}
]
}'
```
### Response
```json
{
"status": "SUCCESS",
"data": {
"api_key_id": "api_2Xd2DgMjouViS2ciMlMvES8R4rb",
"platform_id": "plt_123",
"api_key": "apikey_1ad1c535b0c0093e7b9bf093d7e3444cd0e2ddefab36199216f555c3efa65d63",
"statements": [
{
"permissions": ["payin:read"],
"constraints": {
"merchant": {
"merchant_id": "mid_123"
},
"payin": {
"metadata": {
"account": {
"id": "123"
}
}
}
}
}
],
"status": "ENABLED",
"created_at": "2024-01-01T12:00:00Z",
"updated_at": "2024-01-01T12:00:00Z"
},
"errors": null
}
```
# Manage API keys
***
API keys can be [disabled](https://docs.rainforestpay.com/reference/disable_api_key), [enabled](https://docs.rainforestpay.com/reference/enable_api_key), or [permanently deleted](https://docs.rainforestpay.com/reference/delete_api_key) through the API or the Rainforest Platform Portal.