Receiving a critical action error. What to do?

You will identify the critical authorization error in transfers and choose the most suitable confirmation flow for your integration.

When making certain calls, such as transfers, you may receive the "Critical authorization enabled" error:

{
  "errors": [
    {
      "code": "invalid_action",
      "description": "Your account has critical authorization enabled. To perform this action, provide the confirmation code."
    }
  ]
}

What this error means

Every transfer made on Asaas, except for BaaS accounts, must be approved via SMS token or APP token. When the account has critical authorization enabled, the API blocks the action until the confirmation code is provided, or until the account uses a configured security alternative to automate this process.

Use the error fields to decide the next step:

Choose the confirmation flow

You can handle critical authorization in three ways:

1. SMS token or APP token: use this when the transfer can be manually confirmed by a person with access to the token.
2. IP whitelisting: use this when your integration makes calls from known, controlled IPs. With this configuration, only registered IPs can use the API. If any other IP attempts a call, the API returns an error stating that it is not considered secure.
3. Authentication webhook: use this when you need a more automated flow to validate withdrawals or transfers. Configure the authentication webhook as described in the documentation.

Recommended handling flow

1. Execute the transfer call and check whether the response contains code equal to invalid_action.
2. Read the error's description to confirm whether the action requires a confirmation code.
3. Define the security mechanism according to your scenario:
   • keep SMS token or APP token for manual operations;
   • whitelist IPs when calls always originate from trusted IPs;
   • configure the authentication webhook when you need to automate validation.
4. Configure the chosen mechanism following the related documentation.
5. Retry the blocked operation only after the token confirmation, IP whitelisting, or authentication webhook has been correctly configured.

Critical behaviors and best practices

• When whitelisting IPs, make sure all environments calling the API use registered IPs. Calls made from unregistered IPs will be blocked.
• Do not ignore the invalid_action error. The transfer should not be considered complete while the critical action is pending.
• Log the code and description internally to facilitate diagnosis, but do not expose confirmation codes in logs, screens, or error messages.
• Validate the flow in a controlled environment before automating transfers in production.
• Review the chosen mechanism whenever there is an infrastructure change, such as a server, proxy, gateway, or outbound IP change.