Subaccount API key management

In BaaS operations, the parent account can create, list, update, and delete API keys for its subaccounts without accessing each account individually.

Use this flow to rotate credentials, replace a lost or expired key, and control the lifecycle of the keys used by the integrations.

The value of a key that has already been created cannot be retrieved. If the credential is lost or expires, create a new key.

Before you start

To use the management endpoints:

• temporarily enable access through the Asaas web interface;
• keep the IP Whitelist enabled;
• authorize the outbound IP used by your application;
• authenticate requests with the parent account's API key;
• have the ID of the subaccount that will be managed.

During the Evaluation Period, the subaccount's apiKey is made available. To keep using subaccount keys after this period, the operation must be compliant with Asaas BaaS or qualify as branch subaccounts with the same CNPJ prefix as the main account.

1. Enable key management

The endpoints are blocked by default.

In the Asaas web interface:

1. go to Integrations > API Keys;
2. find Subaccount API Key Management;
3. click Enable access.

After the 2 hours, enable access again before performing new operations.

2. Choose the operation

All calls below are authenticated with the parent account's key.

List keys

Use the list to retrieve the IDs and settings of the subaccount's keys.

The secret value of a key that has already been created is not returned.

Store the accessTokenId when you need to update or delete a key.

Create a key

When creating a new key, provide the name and expiration date as described in the API Reference.

The credential is returned only once. Capture the access_token from the response and store it immediately in a secrets manager.

Do not record the value in logs or admin interfaces.

Update a key

Use the accessTokenId to change the settings of an existing key, such as:

• name;
• enabled status;
• expiration date.

Disabling a key with enabled: false stops authentication for integrations that still use this credential.

Delete a key

Deletion permanently revokes the key.

Do not delete a credential while any application still depends on it. A deleted key cannot be restored.

Rotate keys without interrupting the integration

When you need to replace a credential, keep the current key active until you confirm that the new one is already in use.

%%{init: {"flowchart": {"nodeSpacing": 28,"rankSpacing": 32,"diagramPadding": 8,"padding": 10}}}%%
flowchart TD
    A["Create a new key"] --> B["Store the credential"]
    B --> C["Update the application"]
    C --> D["Validate authentication"]
    D --> E["Disable the old key"]
    E --> F["Monitor failures"]
    F --> G["Delete the old key"]

    classDef inicio fill:#DBEAFE,stroke:#2563EB,color:#1E3A8A,stroke-width:3px,font-size:17px
    classDef validacao fill:#E0F2FE,stroke:#0284C7,color:#0C4A6E,stroke-width:2px,font-size:17px
    classDef sucesso fill:#DCFCE7,stroke:#16A34A,color:#14532D,stroke-width:3px,font-size:17px

    class A inicio
    class B,C,D,E,F validacao
    class G sucesso

    linkStyle default stroke:#94A3B8,stroke-width:2px

This flow should also be used when the original key is replaced due to expiration or compromise.

Monitor the key lifecycle

Use the Webhooks for API keys to track changes without making recurring queries.

The events let you identify the creation, enabling, disabling, deletion, and expiration of keys.

In BaaS subaccounts, especially monitor ACCESS_TOKEN_EXPIRED: these keys are not automatically disabled after three months of inactivity, but they are still subject to permanent expiration after six months.

How to validate the management

After performing an operation:

1. list the subaccount's keys to confirm the current settings;
2. when creating a key, confirm that the credential was stored before discarding the response;
3. when rotating, validate authenticated calls with the new key before disabling the previous one;
4. when deleting a key, first confirm that no system still depends on it.

If you receive 403 Forbidden, confirm that the temporary access is still active and that the application's IP is authorized in the Whitelist.

Next steps

• Configure the IP Whitelist
• Learn about the events for API keys
• Create and manage API keys
• Create subaccounts with Asaas BaaS
• See the Evaluation Period FAQ