IP Whitelisting

This mechanism allows you to define IPs from which we will accept requests using your API key.

Any request received from an IP not contained in the whitelist will be rejected with an HTTP 403 response. Therefore, even if your key is compromised, unless the requests originate from your infrastructure, they will be rejected.

You can define your list of whitelisted IPs by going to User Menu > Integrations > Security Mechanisms.

📘

IP Range Configuration

You can add an authorized IP in an IP range by using x, for example: 192.168.1.x will cover from IP 192.168.1.0 to 192.168.1.255.

🚧

Attention When Configuring Wide IP Ranges

While configuring IP ranges is a flexible tool, whitelisting very large intervals can compromise your account's security and nullify the purpose of this feature.

Risk

A very wide IP range, such as one from a major cloud provider, can include thousands of servers that are not under your control. If your API key is exposed, an attacker operating within that same IP range could make valid requests to your account.

Remember that the goal of the IP Whitelist is to restrict access to the smallest possible set of addresses, following the principle of least privilege.

Recommendation for Cloud Servers

If your application runs in an environment with dynamic egress IPs (such as AWS, GCP, Azure, etc.), we strongly recommend using a NAT Gateway service with a static egress IP. This allows you to add a single IP or a small, controlled set of IPs to your whitelist, ensuring maximum security for your integration.

Why fix IPs?

Fixing IPs for API calls can be a useful and necessary practice.

By fixing IPs, you can restrict access to your APIs, allowing calls only from specific IPs. This helps to block unauthorized or unwanted access.

However, this also requires maintaining a list of authorized IPs and can make access management more complex, but it ensures much more security in your requests to Asaas, especially in White Label operations.

Automated withdrawals for authorized IPs

By default, every withdrawal operation requested via API generates a Critical Event. This means the transaction remains pending, awaiting manual approval via the Web Interface or App to be processed.

To facilitate high-volume automation, you can configure your IP Whitelist to exempt specific origins from this manual approval.

How it works?

In the IP configuration screen, you will find the "Evento crítico em requisições de saque" section.

• Enabled (Default): The system continues to require manual approval for withdrawals, even if coming from a known IP.
• Disabled: The system will automatically process withdrawal requests coming from the listed IPs without generating a pending manual approval.

🚧

Security recommendations

By disabling the generation of critical events, you remove a layer of human verification.

To keep your operation secure and automated, we strongly recommend jointly implementing the External Authorization Mechanism via Webhook. This way, you replace manual approval with systemic approval, ensuring that only transactions recognized by your system are processed.

Operations considered as withdrawals:

• Transfers (Pix and TED);
• Bill payments;
• Mobile phone recharges;
• Indirect Pix/Initiation authorizations;
• Pix refunds.

Inheritance and permission rules:

• This configuration is automatically inherited. If the parent account disables the critical event for its IPs, requests from subaccounts originating from those same IPs will also be processed automatically.
• For security, any change to this configuration requires token validation, following the same rigor as adding a new IP.

Have a complex scenario and need help?

We understand that some architectures may present specific challenges in setting up a static egress IP. If this is your case and the NAT Gateway solution is not applicable, we want to better understand your scenario.

Please fill out this form so that our product team can analyze your use case and we can develop alternative security measures that meet your needs in the future.