---
updatedAt: 2026-10-09T19:49:20.000Z
agentTools:
  projectIndex: https://docs.asaas.com/llms.txt
---

# API Keys

# Create and manage your API keys

The API key identifies your account and authorizes the requests sent to the Asaas API.

<Callout icon="📘" theme="info">
  By the end of this guide, you will know how to create, store, and manage your API keys securely.
</Callout>

## Before you start

The API key:

* must be created through the Asaas web interface;
* cannot be generated through the app;
* can only be created by admin users;
* is exclusive to the environment in which it was generated.

## Create an API key

<Anchor target="_blank" href="https://www.asaas.com/customerApiAccessToken/index">Go to the Integrations area</Anchor> in the web interface to create your key.

![](https://files.readme.io/f4b7e1df6a46013c6702d8c5fa18485eb7751ca3b4f4781f6521641257838e77-image.png)

<Callout icon="⚠️" theme="warn">
  ### Store the key immediately

  The API key is displayed only once and cannot be retrieved later.

  Copy the value and store it in a secure location before leaving the page. If you lose the key, you will need to create a new one.
</Callout>

## Manage your keys

An Asaas account can have up to **10 API keys**.

For each key, you can:

* set a name for identification;
* configure an expiration date;
* temporarily disable or enable it;
* delete it when it is no longer used.

<Callout icon="🔒" theme="default">
  A deleted key cannot be restored.
</Callout>

## Choose the environment

Use the URL that matches your key's environment:

| Environment | Base URL                           |
| :---------- | :--------------------------------- |
| Sandbox     | `https://api-sandbox.asaas.com/v3` |
| Production  | `https://api.asaas.com/v3`         |

<Callout icon="📘" theme="info">
  Sandbox and Production keys are different.

  When switching environments, update the URL and the key used in the request.
</Callout>

During development, use the Sandbox with fictitious data. Switch to Production only after validating all of your integration's flows.

## Store the key securely

Do not store the key:

* directly in the source code;
* in frontend applications;
* in public files;
* in logs;
* in messages, emails, or repositories;
* in unprotected shared workspaces or tools.

Prefer:

* environment variables;
* protected configuration files;
* secrets management services, such as AWS Secrets Manager, Google Cloud Secret Manager, or Azure Key Vault.

Always use HTTPS to transmit authentication information.

<Callout icon="⚠️" theme="warn">
  Do not send your API key to support, third parties, or through customer service channels.
</Callout>

## Control access and rotate your keys

Grant access only to the people and systems that actually need to use the key.

We also recommend:

* monitoring the origin of requests;
* reviewing access periodically;
* defining a rotation policy;
* renewing keys used by many people during development;
* immediately replacing a key that may have been exposed.

The customer is responsible for the security and storage of the key.

## Inactivity lifecycle

Keys that remain unused for long periods are automatically disabled or expired.

These rules apply to parent accounts and subaccounts.

| Inactivity period    | Action                          |
| :------------------- | :------------------------------ |
| 3 months             | The key is disabled             |
| 4 months             | Notice by email and Webhook     |
| 5 months             | New notice by email and Webhook |
| 5 months and 3 weeks | Final notice before expiration  |
| 6 months             | The key is permanently expired  |

### After 3 months

The key is disabled and no longer authenticates requests.

Calls made with it will return `401 Unauthorized`.

You can enable it again under **Integrations > API Keys**.

Asaas sends:

* an email notice;
* the `ACCESS_TOKEN_DISABLED` event.

### After 6 months

The key is permanently expired and cannot be reactivated.

To keep using the integration, create a new key.

Asaas sends:

* an email notice;
* the `ACCESS_TOKEN_EXPIRED` event.

### Upcoming expiration alerts

The `ACCESS_TOKEN_EXPIRING_SOON` event is sent:

* after 4 months of inactivity;
* after 5 months of inactivity;
* one week before expiration.

See the <Anchor target="_blank" href="https://docs.asaas.com/docs/api-key-events#/">Webhook events for API keys</Anchor> to learn about the payloads.

## Exception for BaaS operations

<Callout icon="⚠️" theme="warn">
  In BaaS operation subaccounts, the key is not disabled after 3 months.

  However, it is still subject to permanent expiration after 6 months of inactivity.
</Callout>

For these accounts:

* email notices are not sent;
* only Webhook events are triggered;
* the parent account must monitor the `ACCESS_TOKEN_EXPIRED` event on its subaccounts.

## Manage subaccount keys through the API

The parent account can create, list, update, and revoke API keys for its subaccounts.

This flow lets you replace expired keys without manually accessing each account.

See <Anchor target="_blank" href="https://docs.asaas.com/docs/sub-account-api-key-management">Subaccount API key management</Anchor>.

## Add other layers of security

In addition to the API key, we recommend configuring at least one additional security mechanism.

### IP whitelist

Lets you define the IP addresses authorized to use the key.

Requests originating from unregistered IPs are rejected with `403 Forbidden`.

<Anchor target="_blank" href="https://docs.asaas.com/docs/ip-whitelisting">Configure the IP whitelist</Anchor>.

### Transfer authorization via Webhook

Lets your application validate the transfers requested in the account.

If your system does not recognize a transfer as legitimate, it can be rejected.

<Anchor target="_blank" href="https://docs.asaas.com/docs/mechanism-for-validating-withdrawals-via-webhooks">Configure transfer validation via Webhook</Anchor>.

## Next steps

* <Anchor target="_blank" href="https://docs.asaas.com/docs/authentication-2">Authenticate your requests</Anchor>
* <Anchor target="_blank" href="https://docs.asaas.com/docs/additional-security-mechanisms">Learn about the additional security mechanisms</Anchor>
* <Anchor target="_blank" href="https://docs.asaas.com/docs/ip-whitelisting">Configure the IP whitelist</Anchor>
* <Anchor target="_blank" href="https://docs.asaas.com/docs/sub-account-api-key-management">Manage subaccount keys</Anchor>
* <Anchor target="_blank" href="https://docs.asaas.com/docs/sandbox-2">Learn about the Sandbox</Anchor>

# Sub pages

* [API key pattern with $ and PHP clients](https://docs.asaas.com/docs/api-key-pattern-with-dollar-sign-and-php-clients.md)

# Sibling pages

* [Authentication](https://docs.asaas.com/docs/authentication-2.md)
* [PCI-DSS](https://docs.asaas.com/docs/pci-dss.md)
* [Additional security mechanisms](https://docs.asaas.com/docs/additional-security-mechanisms.md)