API keys

❗️

API version 2023-01-01 deprecating

This version will be deprecated on May 1, 2025. If your platform is on this version, you should upgrade to at least 2023-12-01 to simplify authorization and access new features.

API keys are used to access the Rainforest API. API keys can be created, disabled, and deleted through the API or the Rainforest Platform Portal.

Defining an API key

We use JSONPath to define a set of constraints that must hold in order for the request to be allowed.

Statements grammar

An API key takes a set of STATEMENTS, which are OR'd together. If any STATEMENT matches, then the request is allowed.

A STATEMENT is a flat map of multiple JSONPath equalities that are AND'd together. All equalities in a statement must match for the request to be allowed.

A STATEMENT consists of three types of constraints: resources, actions, and optional filters.

{
  "statements": [
    {
      "$.resource": ["resource_example"],
      "$.action": ["action_example"],
      "$.filters": "filter_example"
    }
  ]
}

Resources

Resources can be explicitly defined to restrict this API key to only perform actions on certain resources. To only allow this API key to perform actions on payins and refunds, the corresponding JSONPath would look like this:

"$.resource": ["payin", "refund"]

To allow this API key to perform actions on all resources, use the wildcard *:

"$.resource": "*"

The resource field can be a single-element array, a string if only one resource is provided, or an array for multiple resources.

Valid resources

• api_key
• billing_profile
• chargeback
• deposit
• device_registration
• http_request
• mcc
• merchant
• merchant_application
• payin
• payin_config
• payment_method
• payment_method_config
• platform
• refund
• routing_number
• session
• user

Note: you must specify the resource this statement is for or use the wildcard * to grant permissions to all resources.

Actions

Actions can be explicitly defined to restrict this API key to only perform certain actions. To only allow this API key to read and update, the JSONPath would look like this:

"$.action": ["read", "update"]

To allow this API key to do all actions, use the wildcard *:

"$.action": "*"

The action field can be a single-element array, a string if only one action is provided, or an array for multiple actions.

Valid actions

• create
• read
• update
• delete

Note: you must specify the action this statement is for or use the wildcard * to grant permissions to all actions.

📘

Statements Cannot be Empty

Each statement must have one action constraint and one resource constraint specified.

Filters

Filters are defined with JSONPath to constrain an API key to data intrinsic to each resource.

For example, to restrict this API key to only see data for merchant mid_456, the corresponding statement would look like this:

"$.filters..merchant.id": "mid_456"

The double-dot syntax is the recursive descent operator, which searches through the object recursively to find the next instance of a matching key.

Example

All statements are evaluated against a hierarchical representation of the query being performed. For example:

{
	"resource": "payin",
	"action": "read",
	"filters": {
		"platform": {
		"id": "plt_123",
			"merchant": {
				"id": "mid_456",
				"payins": {
					"metadata": {
						"account": {
							"id": "123"
						}
					}
				}
			}
		}
	}
}

We want to create an API key that restricts this user to only list payins for a given merchant (mid_456) where the account.id provided in the metadata is equal to 123.

The statements would look like this:

{
	"statements": [
		{
			"$.resource": "payin",
			"$.action": "read",
			"$.filters..merchant.id": "mid_456",
			"$.filters..payins.metadata.account.id": "123"
		}
	]
}

The goal of this statement is to only allow the api key to read payments where the account ID matches a static value.

$.resource matches the root level resource constraint, indicating that we only want to provide permissions on the payin resource.

$.action matches the root level action constraint, indicating that we only want to provide read permissions.

$.filters..payins.metadata.account.id matches the account ID. Note the double-dot syntax for the recursive descent operator discussed above.

Create an API Key

See create an 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": [
  	{
      "$.resource": "payin",
      "$.action": "read",
      "$.filters..merchant.id": "mid_456",
      "$.filters..payins.metadata.account.id": "123"
    }
  ]
}'

Response

{
    "status": "SUCCESS",
    "data": {
        "api_key_id": "api_2Xd2DgMjouViS2ciMlMvES8R4rb",
        "platform_id": "plt_123",
        "api_key": "apikey_1ad1c535b0c0093e7b9bf093d7e3444cd0e2ddefab36199216f555c3efa65d63",
        "statements": [
            {
                "$.resource": ["payin"],
                "$.action": ["read"],
                "$.filters..merchant.id": "mid_456",
                "$.filters..payins.metadata.account.id": "123"
            }
        ],
        "status": "ENABLED",
    },
    "errors": null
}

🚧

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.

Manage API keys

API keys can be disabled, enabled, or permanently deleted through the API or the Rainforest Platform Portal.