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_A1The request may proceed when:
- The child client ID in the
Authorizationvalue is valid. - The
clientIdquery 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.
| Scenario | Result |
|---|---|
The child client ID matches in Authorization and the request body | The request may proceed if all other checks pass |
The child client ID matches in Authorization and the query parameter | The request may proceed if all other checks pass |
The child client ID differs between Authorization and the request body or query parameter | The request is rejected |
| The child client ID appears only in the request body or query parameter | The request is not treated as delegated access |
| The endpoint does not require a separate client ID | The 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
| Method | Endpoint |
|---|---|
POST | /clients |
GET | /clients/{clientId} |
DELETE | /clients/{clientId} |
API-key management
| Method | Endpoint |
|---|---|
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_KEYThe following format is not supported for client or API-key management endpoints:
Authorization: PARENT_A_API_KEY,CHILD_A1These 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 status | Failure code | Message | What to check |
|---|---|---|---|
403 | ERR0.01 | Invalid Authorization header. | Use Authorization: <parent-api-key>,<direct-child-client-id>. Include exactly one child selector, with no whitespace or trailing comma. |
403 | ERR0.01 | This 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. |
403 | ERR0.01 | User is not authorized to access this resource | Check 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. |
400 | ERR0.03 | Client 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_KEYRestrictions 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.
| Term | Meaning |
|---|---|
| Parent client | The client that owns the API key and has one or more directly linked child accounts. |
| Child client | A client account linked directly beneath a parent client in the account hierarchy. |
| Direct child | A child account whose immediate parent is the authenticated parent client. |
| Authenticated client | The client identified by the API key. |
| Effective client | The account in which the requested operation is executed. In a delegated request, this is the selected child client. |
| Parent account context | A request made without a child selector. The authenticated client and effective client are the same account. |
| Delegated child context | A request where a parent selects an eligible direct child using a child selector in the Authorization value. |
| Child selector | The direct child client ID appended to the parent API key after a comma. |
| Delegated business API request | A supported business API request performed in the selected child account’s context, such as creating a Payment or Payment Request. |
| Parent-management API | An API used to create, retrieve, disable, or manage child clients or their API keys. These endpoints use the existing parent-management request format. |
| Permitted operations | The 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 access | The Azupay-managed capability that allows an enabled parent client to use its API key for permitted operations on eligible direct child accounts. |
Updated 4 days ago
