Scoped Sub-Account Actions

Login as a Sub-Account and Run a Scoped Action

Use this flow when you need a customer-specific session that is limited to one downstream sub-account, such as an embedded dashboard, a customer portal, or any operation that should not accidentally affect another customer context.

✅ Before you start

Complete these steps before you use scoped sub-account authentication:

Create the sub-account and store its ID.
Authenticate successfully with your master credentials.
Decide whether you need a scoped token or whether master auth plus X-Sub-Account-Id is sufficient.
Prepare to store and label scoped tokens separately from master tokens.

📚 Use this page with the recipe

This guide explains when to use scoped sub-account authentication and the minimum sequence. For the step-by-step implementation, use the recipe:

Login as a Sub-Account and Run a Scoped Action Recipe →

The scoped sub-account auth workflow

This use case follows a simple sequence:

Choose scoped auth for a customer-specific session.
Request a scoped token using the subAccountId during login.
Call customer-specific endpoints with the scoped token.
Keep scoped tokens separate from master orchestration credentials.

What makes this use case different?

Unlike master auth plus X-Sub-Account-Id, this pattern is specifically for cases where:

one session should only ever operate on one downstream customer
you want to reduce the risk of acting on the wrong sub-account by mistake
your UI or backend session should be limited to customer-scoped balances, wallets, or activity

Where to go deeper

Use the product guides when you need implementation detail for a specific step:

Success indicators

Signal	What it means
Scoped token returned	The login response is limited to the requested sub-account context.
Customer-specific request succeeds	The scoped token can access only the expected downstream resources.
No cross-customer leakage	The session does not accidentally expose another sub-account’s balances or actions.

Troubleshooting

Issue	What to check
Scoped login fails	Confirm the `subAccountId` exists and belongs to the correct platform context.
Wrong customer data appears	Verify you are using the intended scoped token and not a master token or another customer’s token.
Scoped requests cannot find wallets or balances	Confirm the sub-account is active and already has the resources your UI or service expects.

Next steps


Global Collection to Payout → See the advanced downstream flow for collecting funds and sending them onward from the same customer context.	Retry a Timed-Out Payout Safely → Learn how to recover safely when a payout request returns an uncertain result.