> ## Documentation Index
> Fetch the complete documentation index at: https://developers.uqpay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Connected Accounts

> Manage subaccounts and make API requests on their behalf using the x-on-behalf-of header.

UQPAY uses a master account and subaccounts model. Your master account holds the API credentials, and all subaccounts under it share those same credentials. This page explains how to list connected subaccounts and make API requests on their behalf.

## Account architecture

| Account type   | Role                                                                                                   |
| -------------- | ------------------------------------------------------------------------------------------------------ |
| Master account | Top-level account that holds API credentials and webhook configuration                                 |
| Subaccount     | An individual or company entity (merchant, customer, or subsidiary) operating under the master account |

All API credentials and webhook settings are configured once at the master account level and apply to all subaccounts. To create subaccounts, see [Account Onboarding](/account-center/v1.6/guide/account-onboarding).

## List connected accounts

Call the [List Connected Accounts](/account-center/v1.6/api-reference/list-connected-accounts) API to retrieve all subaccounts linked to your master account.

```bash theme={null}
curl -X GET "https://api-sandbox.uqpaytech.com/api/v1/accounts?page_size=10&page_number=1" \
  -H "x-auth-token: YOUR_ACCESS_TOKEN"
```

The response contains an array of account objects. Each object includes an `account_id` field — you'll use this value when making requests on behalf of that subaccount.

## Acting on behalf of a subaccount

To scope an API request to a specific subaccount, include the `x-on-behalf-of` header set to the subaccount's `account_id`.

```bash theme={null}
curl -X GET "https://api-sandbox.uqpaytech.com/api/v1/issuing/cardholders?page_size=10&page_number=1" \
  -H "x-auth-token: YOUR_ACCESS_TOKEN" \
  -H "x-on-behalf-of: SUBACCOUNT_ID"
```

<Note>
  If you omit `x-on-behalf-of`, the request is treated as initiated by the master account by default.
</Note>

Although API credentials are shared, data and transaction context are isolated per account. The `x-on-behalf-of` header ensures that operations are scoped to the correct account.

## When NOT to send `x-on-behalf-of`

The header is intended for endpoints that operate on subaccount-scoped resources. Do not include it on master-account-level operations — for example, listing connected accounts or minting an access token. If a request does not target a subaccount-scoped resource, omit `x-on-behalf-of`.

## Error handling

If the `x-on-behalf-of` value is invalid or the subaccount is deactivated, the API returns:

```json theme={null}
{
  "type": "account_error",
  "code": "sub_account_not_found",
  "message": "sub-account associated with the on-behalf-of not found or deactivated"
}
```

To resolve this, verify that the `account_id` is correct and that the target subaccount is active.

<Tip>
  The `account_id` must be in UUID format (e.g. `18523f72-f4de-4f9c-bb8e-ec7d1c4f32be`), not the short reference ID.
</Tip>

## Related

* [Account Onboarding](/account-center/v1.6/guide/account-onboarding)
* [List Connected Accounts API](/account-center/v1.6/api-reference/list-connected-accounts)
* [Retrieve Account API](/account-center/v1.6/api-reference/retrieve-account)