🚧

Upgrade to the latest version

These docs are for version 2023-12-01. We encourage you to upgrade to version 2024-10-16 to access new features. Please see the changelog for more information.

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

What is an action?

An action is a specific operation on a resource in the Rainforest API.

Valid actions

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

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:

"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 --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 --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, 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 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

{
    "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, enabled, or permanently deleted through the API or the Rainforest Platform Portal.