Component sessions

❗️

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.

A session is used to temporarily grant your merchant or user component permissions. Sessions use JSONPath to determine the policy.

Defining a policy

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

Policy grammar

A policy 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 policy 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 policy to only perform actions on certain resources. To only allow this policy to perform actions on payins and refunds, the corresponding JSONPath would look like this:

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

To allow this policy 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 policy to only perform certain actions. To only allow this policy to read and update, the JSONPath would look like this:

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

To allow this policy 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 a policy to data intrinsic to each resource.

For example, to restrict this policy 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 policies 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 a policy 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 policy would look like this:

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

The goal of this policy is to only allow the session 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.

TTL

Sessions are temporary and must have a time to live in seconds. The maximum allowed TTL is 24 hours (86400 seconds).

Create a Session

See create a temporary session

Request

curl --request POST \
--url 'https://api.rainforestpay.com/v1/sessions' \
--header 'Authorization: Bearer {{api_key}}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "ttl": 3600,
  "statements": [
  	{
      "$.resource": "payin",
      "$.action": "read",
      "$.filters..merchant.id": "mid_456",
      "$.filters..payins.metadata.account.id": "123"
    }
  ]
}'

Response

{
    "status": "SUCCESS",
    "data": {
        "session_id": "ses_2IrcnEso2z8vFbsdNb7COwoityc",
        "session_key": "session_35c2bb7f5dcc0116d16a47305cabe92206a7a6c2dac9282689aa34fccda1f4d7",
        "statements": [
            {
                "$.resource": ["payin"],
                "$.action": ["read"],
                "$.filters..merchant.id": "mid_456",
                "$.filters..payins.metadata.account.id": "123"
            }
        ],
        "expires_at": "2022-12-13T10:55:07.22893-05:00"
    },
    "errors": null
}

You should now be able to embed the Rainforest components with the session_key from the response.

<rainforest-example-component 
	session-key="session_35c2bb7f5dcc0116d16a47305cabe92206a7a6c2dac9282689aa34fccda1f4d7"
></rainforest-example-component>