Login as Sub-Account

Authenticate into a specific sub-account context when you need a token that is limited to one downstream customer’s wallets, balances, transactions, and payout activity.

✅ Before you log in as a sub-account

Complete these steps first:

1. Create the sub-account and store its ID.
2. Authenticate successfully with your master credentials.
3. Decide whether you need a scoped token or whether master auth + X-Sub-Account-Id is enough for your use case.
4. Use scoped auth only when the session should be limited to a single customer context.

The Scoped Token Pattern

By passing a subAccountId during the login handshake, Verto returns a JWT that is limited strictly to that user's resources. This is the recommended pattern for building user-facing dashboards.

When to use scoped auth vs header scoping

Use the approach that matches how your application is structured:

🚀 Execution Workflow

Authenticate as the sub-account to receive a context-locked accessToken.

curl -X POST https://api.sandbox.vertofx.com/v2/auth/token \
  -H "Content-Type: application/json" \
  -d '{
    "clientId": "YOUR_CLIENT_ID",
    "apiKey": "YOUR_API_KEY",
    "mode": "apiKey",
    "subAccountId": "sub_acc_778899"
  }'

Store the returned scoped token separately from your master token. Use it only for operations that should be limited to that one downstream customer.

🏗️ Token Capabilities

Once you have the scoped token, you can perform the following actions without needing to pass the X-Sub-Account-Id header manually in every call, as the token already carries that identity.

Use this model when you want to reduce the risk of acting on the wrong downstream customer by mistake.

Troubleshooting

🎯 Next Steps