Acting on behalf of child accounts

Parent clients can use an existing API key to perform permitted business API operations for an eligible direct child account. This means you may not need to store and rotate a separate API key for every child account.

Before you begin

Delegated child-account access must be enabled by Azupay. Contact Azupay Support or your account representative if you need this capability enabled.

A delegated request is allowed only when:

  • The parent client and API key are enabled.
  • Delegated child-account access is enabled for the parent.
  • The selected account is an enabled direct child of the parent.
  • The requested operation is permitted for the parent API key.

Delegated access currently supports direct children only. You cannot select:

  • The parent account itself
  • A grandchild or deeper descendant
  • An account belonging to another parent

Select a child account

To make a request on behalf of a direct child, append the child’s client ID to the parent API key in the Authorization value:

Authorization: <parent-api-key>,<direct-child-client-id>

The parent API key authenticates the request, while the appended child client ID selects the account context in which the operation runs.

Payment Request example

The following example creates a Payment Request for the selected child account:

POST /v1/paymentRequest
Authorization: <parent-api-key>,<direct-child-client-id>
Content-Type: application/json
{
  "PaymentRequest": {
    "clientId": "<direct-child-client-id>",
    "clientTransactionId": "INV-0000001-1",
    "paymentAmount": 32.12,
    "paymentDescription": "Payment for invoice INV-0000001"
  }
}

The clientId in the request body must match the child client ID selected in the Authorization value.

Reports example

The Reports API requires the child client ID in the clientId query parameter. The value must match the child client ID selected in the Authorization value:

GET /v1/report?clientId=<direct-child-client-id>&month=2026-10&timezone=Australia%2FSydney
Authorization: <parent-api-key>,<direct-child-client-id>

For example:

GET /v1/report?clientId=CHILD_A1&month=2026-10&timezone=Australia%2FSydney
Authorization: <parent-api-key>,CHILD_A1

The request may proceed when:

  • The child client ID in the Authorization value is valid.
  • The clientId query parameter identifies the same child.
  • The parent is authorised to act on behalf of that child.
  • The parent API key has permission to use the Reports API.

Matching client IDs

The child client ID in the Authorization value is authoritative. If a client ID also appears in the request path, query parameters, or request body, it must identify the same child.

ScenarioResult
The child client ID matches in Authorization and the request bodyThe request may proceed if all other checks pass
The child client ID matches in Authorization and the query parameterThe request may proceed if all other checks pass
The child client ID differs between Authorization and the request body or query parameterThe request is rejected
The child client ID appears only in the request body or query parameterThe request is not treated as delegated access
The endpoint does not require a separate client IDThe selected child from Authorization is used as the effective client

A mismatched client ID does not create, return, or change resources for either account

Client and API-key management endpoints

Parent clients must use their existing parent-management authorisation format when managing child clients or their API keys:

Authorization: <parent-api-key>

Do not append a child selector to the Authorization value for these endpoints:

Client management

MethodEndpoint
POST/clients
GET/clients/{clientId}
DELETE/clients/{clientId}

API-key management

MethodEndpoint
POST/client/{clientId}/apiKeys
GET/client/{clientId}/apiKeys
GET/client/{clientId}/apiKeys/{apiKeyId}
PATCH/client/{clientId}/apiKeys/{apiKeyId}

For example:

GET /client/CHILD_A1/apiKeys
Authorization: PARENT_A_API_KEY

The following format is not supported for client or API-key management endpoints:

Authorization: PARENT_A_API_KEY,CHILD_A1

These endpoints use the existing parent-management contract. The child account is identified by the endpoint path or request body, depending on the operation.

Permissions

Delegated access does not increase the permissions of an API key.

The requested operation must be included in the parent API key’s permitted operations. If it is not permitted, the request is denied even when delegated child-account access is enabled.

Troubleshooting

If a delegated request fails, check the HTTP status, details.failureCode and returned message.

HTTP statusFailure codeMessageWhat to check
403ERR0.01Invalid Authorization header.Use Authorization: <parent-api-key>,<direct-child-client-id>. Include exactly one child selector, with no whitespace or trailing comma.
403ERR0.01This operation is not permitted for this client.For a request with a child selector, confirm with Azupay that delegated child-account access is enabled for the parent.
403ERR0.01User is not authorized to access this resourceCheck that the parent account, parent API key and selected child are enabled; the API key is correct; the selected account is a direct child; and the parent API key permits the requested operation. For client or API-key management endpoints, remove the child selector.
400ERR0.03Client ID does not match the delegated child in Authorization.Make sure any client ID in the request path, query parameters or body matches the child selected in Authorization.

Correct the request, permissions or account configuration before retrying. If you need help confirming delegated access or account status, contact Azupay Support or your account representative.

Requests without a child selector

When the API key is used without a child selector, the request continues to run in the API key owner’s account context:

Authorization: PARENT_A_API_KEY

Restrictions for DP, TIP and SIP accounts

When using an API key in their own account context, Distribution Partners (DPs), Technical Integration Partners (TIPs) and System Integration Partners (SIPs) can only create, list and disable child accounts, and manage child API keys, subject to their API key’s permittedOperations.

All other API operations, including creating payments and payment requests, are blocked in their own account context.

Suggested change management plan

Existing clients can adopt delegated child-account access in stages.

1. Update your integration

Update your integration to identify the child client when making delegated requests with the parent API key.

2. Confirm configuration with Azupay

Contact Azupay when you are ready to enable the feature.

Before enabling it, confirm that:

  • The parent client is eligible.
  • The parent API key is enabled and the required business API operations are permitted for the parent API key.

3. Use delegated access for new clients

When onboarding a new child client, use the parent API key and the child client ID for supported business API requests.

4. Continue using existing child API keys

Existing or “backbook” clients can continue using their current child API keys. No immediate migration is required.

5. Migrate existing clients when ready

You can decide when to move each existing client from its child API key to the parent API key.

Migration reminder

Keep the existing child API key available until the client has been successfully migrated and tested. Do not disable or remove it until you have confirmed that it is no longer required.

Glossary

The following terms are used throughout this guide to describe parent accounts, child accounts, and delegated API requests.

TermMeaning
Parent clientThe client that owns the API key and has one or more directly linked child accounts.
Child clientA client account linked directly beneath a parent client in the account hierarchy.
Direct childA child account whose immediate parent is the authenticated parent client.
Authenticated clientThe client identified by the API key.
Effective clientThe account in which the requested operation is executed. In a delegated request, this is the selected child client.
Parent account contextA request made without a child selector. The authenticated client and effective client are the same account.
Delegated child contextA request where a parent selects an eligible direct child using a child selector in the Authorization value.
Child selectorThe direct child client ID appended to the parent API key after a comma.
Delegated business API requestA supported business API request performed in the selected child account’s context, such as creating a Payment or Payment Request.
Parent-management APIAn API used to create, retrieve, disable, or manage child clients or their API keys. These endpoints use the existing parent-management request format.
Permitted operationsThe operations assigned to an API key. An operation must be permitted for the parent API key before it can be performed in either the parent or delegated child context.
Delegated child-account accessThe Azupay-managed capability that allows an enabled parent client to use its API key for permitted operations on eligible direct child accounts.



Did this page help you?