DiscordStatus
Guias / Guides

API key events

Receive notifications to monitor all actions and state changes that occur on your API keys, increasing the security and operational visibility of your account

Use API key events to track creations, enablements, disablements, deletions and expirations without periodically querying the state of your keys.

Notifications are also sent when the change is made through the web interface. In operations with subaccounts, use the event data to identify which account had its key changed.

Available events

EventWhen it occursHandling in the integration
ACCESS_TOKEN_CREATEDA new API key is created.Record the key by its accessToken.id and sync its state.
ACCESS_TOKEN_ENABLEDA disabled key is reactivated.Update the key as enabled.
ACCESS_TOKEN_DISABLEDA key is disabled manually or by the automatic lifecycle.Update the key as disabled and check accessToken.disableReason.
ACCESS_TOKEN_DELETEDA key is permanently removed.Remove or invalidate the key reference in your system.
ACCESS_TOKEN_EXPIRING_SOONA key is close to expiring due to inactivity.Notify or take the necessary actions before expiration.
ACCESS_TOKEN_EXPIREDA key expires permanently due to inactivity or the configured expiration date.Consider the key invalid for new authentications.

ACCESS_TOKEN_EXPIRING_SOON is related to the inactivity lifecycle and is not sent for keys that have a manually configured expiration date.

To learn about the deadlines and rules for expiration due to inactivity, see API keys.

Event payload

The notification is sent via POST with the event and the current key data.

{
  "id": "evt_6561b631fa5580caadd00bbe3b858607&9193",
  "event": "ACCESS_TOKEN_CREATED",
  "dateCreated": "2026-05-19 12:25:15",
  "account": {
    "id": "47ed0d25-f9fb-4b35-b23a-d8895caf92b7",
    "ownerId": null
  },
  "accessToken": {
    "id": "cf7662a4-a7dd-40ec-b8de-d28617729501",
    "name": "TEST Key",
    "enabled": false,
    "dateCreated": "2026-05-19 12:25:15",
    "disableReason": "MANUAL",
    "expirationDate": null,
    "projectedExpirationDateByLackOfUse": null
  }
}

Important payload fields

FieldDescription
idUnique identifier of the event. Use it for idempotence.
eventIdentifies the change made to the key.
account.idIdentifier of the account related to the event.
accessToken.idKey identifier.
accessToken.enabledIndicates whether the key is enabled.
accessToken.disableReasonReason for disabling, when applicable.
accessToken.expirationDateManually configured expiration date.
accessToken.projectedExpirationDateByLackOfUseProjected expiration date due to inactivity.

Use event to identify the change that originated the notification and the accessToken data to update the key's state in your system.

Possible values of accessToken.disableReason

ValueScenario
MANUALManually disabled through the web application or the API.
LACK_OF_USEAutomatically disabled due to inactivity.

How to handle the events

To receive these events, configure an account Webhook with the ACCESS_TOKEN_* events your integration needs.

When receiving a notification:

  1. identify the account through the account.id field;
  2. identify the change through the event field;
  3. persist the id to prevent duplicate processing;
  4. use accessToken.id to find the key in your system;
  5. update the key's state with the data received;
  6. respond HTTP 200 after confirming persistence and process additional rules asynchronously.

Webhooks follow the at least once model, so the same event may be sent more than once. The same event keeps the same id across redeliveries.

See how to implement idempotence in Webhooks.

When using authToken in the Webhook, validate the asaas-access-token header to authenticate the notifications received.

🚧

Attention

  • As new products and features are added to Asaas, new attributes may be included in the Webhook. It is very important that your code is prepared not to throw exceptions if Asaas returns new attributes that your application does not handle, as this may interrupt the sync queue.
  • We will send an email and announce on our Discord when new fields are added to the Webhook. The email will be sent to the notification email address defined in the webhook settings.

Next steps

Updated 16 days ago

Did this page help you?