Managing Subtenants

Each subtenant represents an individual sub-developer and is managed through our subtenant APIs, giving them an isolated environment within your program. A subtenant has its own users, cards, and transactions, while sharing your program’s API keys, collateral, and billing.

​

Step 1: Create a subtenant

To get started, create a subtenant. The response includes:

• An id — this is the value you pass in the Sub-Tenant-Id header in later requests.
• An applicationCompletionLink — share this link with the sub-developer so they can complete compliance requirements.

To retrieve the compliance link again later, list all subtenants or retrieve the subtenant by ID. To make changes, such as renaming a subtenant, update the subtenant.

​

Step 2: Use subtenants in API requests

Subtenants are designed to require minimal changes to your integration. You’ll continue using the same API keys and endpoints. To make a request on behalf of a subtenant, include the Sub-Tenant-Id header. API keys always belong to your parent tenant — you can’t create or use API keys scoped to a subtenant. For this reason, the key management (/issuing/keys) and subtenant management (/issuing/subtenants) endpoints reject requests that carry the Sub-Tenant-Id header; call them without it. Double-check the Sub-Tenant-Id header on every request. The flexible setup means fewer safeguards, and a wrong value creates resources under the wrong tenant.

​

Step 3: Configuration inheritance

When you update your parent tenant’s configuration, Rain applies the change to all of your subtenants so they stay in sync with your program. Don’t rely on per-subtenant configuration differences persisting — a later change to the parent overwrites them. The webhook URL is the exception. To give a subtenant its own webhook URL, call update a subtenant with a webhookUrl value. Once a subtenant has its own webhookUrl, that URL receives the subtenant’s webhook events, and Rain preserves it even when you change the parent tenant’s configuration. Webhook events for a subtenant’s resources are signed with the same signing key as your parent tenant’s events, so verify them with the signing secret you already use.

​

Moving users and companies between subtenants

You can move existing users and companies into a subtenant — from your parent tenant or from another one of your subtenants — together with all of their related data (users, cards, and transactions):

• Move a company to a subtenant — moves the company and all of its users.
• Move a user to a subtenant — for individual consumer users only.

Call these endpoints with your parent tenant’s API key and without the Sub-Tenant-Id header. The target must be one of your subtenants — you can’t move a user or company back to the parent tenant. The target subtenant must also be authorized to serve that customer type and support exactly the same currencies as the source tenant, and moving from a Partner-Managed tenant to a Rain-Managed tenant is not supported yet.

​

What’s Next