Authentication permission groups

Rainforest is introducing permission groups, a higher-level API for permissions. Permission groups let you:

• simplify your integration code, replacing many lines of hard-to-understand configuration with a single, clearly-named group
• take advantage of new Rainforest features as they're added, without needing to update your integration code

How it works

When creating a Session or API key, you no longer need to carefully craft the right set of permissions statements.

Instead, you can refer to one of our named permission groups, like group#merchant_onboarding_component, to give it the authentication needed to complete merchant onboarding.

Why are we making this change?

Previously, when creating a Session or an API key, you had to specify an exact list of all the actions and resources it was allowed to access. Over time, these configurations could grow to be long and hard to understand.

For example, to let a merchant fill out our onboarding component, which requires working with a number of our resources, you had to provide 13 lines of statements:

{ 
    "statements": [
        {
            "$.filters..merchant.id": "{{Replace with the merchant_id}}",
            "$.resource": ["merchant", "merchant_application"],
            "$.action": ["read", "update", "create"]
        },
        {
            "$.resource": ["payment_method_config", "payment_method"],
            "$.action": ["create", "read", "update"]
        },
        {
            "$.resource": ["routing_number"],
            "$.action": ["read"]
        }
    ]
}

This introduced two problems:

1. You have to specify the statements correctly, or risk users either running into authorization errors or being able to do more than they were supposed to.
2. As Rainforest introduces new features via new resources and actions, you would have to update your session statements before your users would be able to take advantage of them.

Permission groups

To solve these problems, we're introducing permission groups, which give clear names to a collection of permissions.

To let a merchant complete their onboarding, the session statements need to include:

{
    "statements": [{
        "permissions": ["group#merchant_onboarding_component"],
        "constraints": {
            "merchant": {
                "merchant_id": "mid_123"
            }
        }
    }]
}

You specify the merchant_onboarding_component group, constrained to only work within their merchant. Rainforest handles the rest.

This layer of indirection means that you can simplify and better understand your permissions code. It also means that Rainforest can introduce new features in our onboarding flow (more on that soon!) and if they require new resources or actions, your users will automatically be able to take advantage of them without you needing to update your integration code.

For more details on the available groups and constraints, see our new guide for component sessions and API keys.

How to upgrade

Because some parts of this change are not backwards-compatible, we have introduced a new API version that you will need to use for API calls to create sessions and API keys.

If you have a current integration with us, you will need to pass the Rainforest-Api-Version header with the value 2023-12-01 in the request in order to specify the new permission groups.

On the "Create API key" screen, click the "Advanced" dropdown to choose the 2023-12-01 API version.

The Statements will reflect the new permissions.

Once you complete the migration, please let us know via your partner Slack channel or [email protected]. We can bump your default API version so that you'll automatically be on the latest version and you no longer need to specify it in a header.