Endpoint responsible for updating the settings of an API key that already exists in an Asaas subaccount.

With this endpoint, the parent account can change information for a subaccount API key, such as name, enabled status, and expiration date, without needing to manually access the subaccount through the Web interface.

This functionality is part of subaccount API key management and is indicated for operations that need to control the credential lifecycle in a centralized and secure way.

When to use this endpoint

Use this endpoint when your integration needs to:

• rename an API key of a subaccount;
• enable a previously disabled key;
• temporarily disable a key without deleting it;
• change the expiration date of an existing key;
• standardize names of keys used by internal systems;
• perform rotation or maintenance of subaccount credentials;
• correct a key created with an incorrect name or expiration;
• control access for integrations linked to subaccounts.

This endpoint is especially useful for partners, White Label platforms, marketplaces, ERPs, and BaaS operations that manage multiple subaccounts and need to keep credentials organized and secure.

When not to use

Do not use this endpoint to:

• create a new API key;
• permanently delete or revoke a key;
• list existing keys of a subaccount;
• update cadastral data of the subaccount;
• change permissions of a key outside the accepted fields;
• retrieve the value of an API key already created.

If you need to create a new key, use the endpoint for creating an API key for a subaccount.

If you need to permanently remove a key, use the endpoint for deleting or revoking an API key.

Access requirements

Because this is a sensitive operation, this endpoint has specific security requirements.

Before calling this endpoint, check whether:

• the parent account has linked subaccounts;
• access to subaccount key management has been enabled in the Web interface;
• the call is being made within the temporary release period;
• the IP Whitelist is enabled;
• the outbound IP of your application is authorized;
• the request is authenticated with the parent account API key;
• the informed subaccount exists and belongs to the authenticated parent account;
• the informed accessTokenId corresponds to an existing API key of the subaccount.

Recommended flow

In a typical integration, updating an API key of a subaccount should follow the flow below:

Enable access to key management in the Web interface
↓
Ensure that the IP Whitelist is enabled
↓
List the API keys of the subaccount
↓
Identify the accessTokenId of the key that will be updated
↓
Build the payload with name, enabled, and expirationDate
↓
Send the update
↓
Validate the API response
↓
Update your application’s internal controls

The update depends on the accessTokenId. Therefore, before calling this endpoint, list the subaccount’s keys or use the identifier returned at the time the key was created.

Path parameters

The id parameter must correspond to the subaccount linked to the authenticated parent account.

The accessTokenId parameter must correspond to an existing API key of that subaccount.

Body parameters

name

Enter a name that makes it easier to identify the key.

Examples:

ERP Integration
Checkout Integration
API Rotation - July 2026

enabled

Defines whether the key will be enabled or disabled.

Accepted values:

Disabling a key can interrupt integrations that depend on it. Before changing this field to false, confirm whether the application is already using another valid key.

expirationDate

Defines the expiration date and time of the key.

Use a date and time format compatible with date-time.

Example:

2026-12-31T23:59:59Z

Request example

curl --request PUT \
  --url https://api-sandbox.asaas.com/v3/accounts/acc_000000000001/accessTokens/atk_000000000001 \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --header 'access_token: $ASAAS_PARENT_API_KEY' \
  --data '{
    "name": "ERP Integration - Subaccount",
    "enabled": true,
    "expirationDate": "2026-12-31T23:59:59Z"
  }'

Response example

{
  "id": "atk_000000000001",
  "name": "ERP Integration - Subaccount",
  "enabled": true,
  "expirationDate": "2026-12-31T23:59:59Z"
}

Update behavior

When updating an API key of a subaccount:

• the key remains associated with the same subaccount;
• the key identifier is not changed;
• the secret value of the key is not returned again;
• the endpoint changes only the fields sent in the body accepted by the route;
• changes to the enabled field can immediately affect integrations that use the key;
• changes to expirationDate modify the key lifecycle;
• the update does not create a new key;
• the update does not permanently revoke the key.

The Asaas API key is unrecoverable after creation. Therefore, this endpoint should not be used to try to consult the secret value of the credential.

Important business rules

When using this endpoint, consider that:

• the call must be made by the parent account;
• the subaccount must belong to the authenticated parent account;
• the accessTokenId must belong to the informed subaccount;
• access to the management endpoints must be enabled in the Web interface;
• access release is temporary;
• the IP Whitelist must be enabled;
• the source IP of the request must be authorized;
• name, enabled, and expirationDate are required in the body;
• disabling a key can interrupt integrations in use;
• deleting a key is different from disabling a key;
• a deleted key cannot be restored.

Difference between updating, disabling, and deleting

Precautions in key rotation operations

In key rotation scenarios, avoid disabling the old key before confirming that the new key is already being used by the application.

Recommended flow:

Create a new key for the subaccount
↓
Store the new key securely
↓
Update the application to use the new key
↓
Validate calls with the new key
↓
Disable the old key
↓
Monitor authentication errors
↓
Delete the old key only when there is no longer any dependency

This precaution reduces the risk of unavailability in integrations that depend on the subaccount.

Common errors

Some common errors when using this endpoint include:

Operational impacts

Updating an API key can directly impact the availability of the subaccount integration.

Incorrect settings may cause:

• interruption of authenticated calls;
• 401 Unauthorized failures;
• temporary loss of communication between your application and the subaccount;
• unexpected credential expiration;
• difficulty tracking which system uses each key;
• need for emergency rotation;
• failures in charge, consultation, webhook, or onboarding flows that depend on the updated key.

Therefore, treat key updates as a sensitive operation and record internal change logs.

Best practices

When updating API keys of subaccounts, it is recommended to:

• use descriptive names for each key;
• maintain an internal inventory of which systems use each key;
• avoid disabling a key without confirming that it is no longer in use;
• plan maintenance windows for critical changes;
• validate the new configuration in Sandbox before applying it in Production;
• store keys in secret managers;
• monitor 401 errors after changes;
• keep the IP Whitelist restricted to the smallest possible set of addresses;
• avoid broad IP ranges;
• register user, system, date, and reason for the update;
• use key lifecycle webhooks, when applicable.

Sandbox precautions

This endpoint can be tested in Sandbox.

It is recommended to validate the following scenarios:

• list API keys of a subaccount;
• update the name of a key;
• change enabled to false;
• try to use a disabled key;
• change enabled to true;
• update the expiration date;
• test a call with an unauthorized IP;
• test the behavior after the temporary release expires.

These tests help define the expected behavior before operating in Production.

Related content

See also:

• Subaccount API key management;
• List API keys of a subaccount;
• Create API key for a subaccount;
• Delete API key of a subaccount;
• API keys;
• IP Whitelist;
• Subaccount creation;
• Authentication;
• What can be tested in Sandbox.