API Key Permission Management

Define which resources and actions each API key can access.

Using only the necessary permissions reduces the impact if a credential is compromised.

📘
By the end of this guide, you will know how to configure permissions when creating or updating an API key.

How permissions work

When creating or editing a key through the web interface, or through the API in the case of subaccounts, define the permissions array.

Each item contains:

Field	Description	Example
`name`	Resource that can be accessed	`PAYMENT`, `TRANSFER`
`scope`	Allowed access level	`READ`, `READ_WRITE`

The available scopes are:

Scope	Access
`READ`	Allows read operations, such as `GET`
`READ_WRITE`	Allows read and write operations, such as `POST`, `PUT`, and `DELETE`

⚠️
Define permissions explicitly
If accessTokenConfig or permissions are not sent, the key will be created with all permissions in the READ_WRITE scope.
We recommend applying the principle of least privilege and granting only the resources your integration needs.
Defining permissions may become mandatory in future updates.

Create a key with permissions

When you create a subaccount, send the accessTokenConfig object.

Endpoint

POST /v3/accounts

Request example

{
  "name": "Integrated Subaccount",
  "email": "[email protected]",
  "cpfCnpj": "12345678000199",
  "...": "...",
  "accessTokenConfig": {
    "name": "Financial Integration Key",
    "permissions": [
      {
        "name": "PAYMENT",
        "scope": "READ_WRITE"
      },
      {
        "name": "TRANSFER",
        "scope": "READ"
      },
      {
        "name": "WEBHOOK",
        "scope": "READ_WRITE"
      }
    ]
  }
}

In this example, the key will be able to:

view and manage charges;
view transfers, without creating or changing them;
view and manage Webhooks.

Response example

{
  "object": "account",
  "id": "8de2fa50-589e-4a95-a545-e6bd6e1ed71a",
  "...": "...",
  "accessToken": {
    "id": "3e9d4210-4948-4829-a0f0-c06b69ce2fa3",
    "name": "Financial Integration Key",
    "enabled": true,
    "expirationDate": null,
    "dateCreated": "2026-01-14 09:51:37",
    "permissions": [
      {
        "name": "PAYMENT",
        "scope": "READ_WRITE"
      },
      {
        "name": "TRANSFER",
        "scope": "READ"
      },
      {
        "name": "WEBHOOK",
        "scope": "READ_WRITE"
      }
    ],
    "projectedExpirationDateByLackOfUse": null,
    "apiKey": "$aact_hmlg_....l"
  }
}

Check the accessToken.permissions object to confirm the permissions assigned to the key.

Update an existing key

You can also change the permissions of existing subaccount API keys.

See Subaccount API key management.

📘
In the update endpoints, send only the permissions array in the body.

Insufficient permission error

When a key tries to access a resource without the required permission, the API returns 403 Forbidden.

Example:

{
  "errors": [
    {
      "code": "insufficient_permission",
      "description": "The provided API key does not have the required permissions. Check that the key has the FINANCIAL_TRANSACTION:READ scope to access the requested resource"
    }
  ]
}

To fix it:

identify the permission indicated in the message;
check the key's current permissions;
update the scope or use another authorized key;
avoid granting permissions that are not needed.

Available permissions

The table below maps the resources shown in the Asaas interface to the names used by the API.

Resource	Permission	Related endpoint
Customers	`CUSTOMER`	Create new customer
Notifications	`CUSTOMER_NOTIFICATION`	Update notifications in batch
Charges	`PAYMENT`	Create new charge
Charge refunds	`PAYMENT_REFUND`	Refund charge
Chargeback	`CHARGEBACK`	Create chargeback dispute
Installments	`INSTALLMENT`	Create installment
Subscriptions	`SUBSCRIPTION`	Create new subscription
Static QR Code	`PIX_CREDIT`	Create static QR Code
Payment link	`PAYMENT_LINK`	Create payment link
Checkout	`CHECKOUT`	Create new Checkout
Credit card	`CREDIT_CARD`	Tokenize credit card
Anticipations	`ANTICIPATION`	Request anticipation
Anticipation settings	`ANTICIPATION_CONFIG`	Update automatic anticipation
Charge guarantee	`ESCROW`	Close charge guarantee
Escrow Account configuration	`ESCROW_CONFIG`	Create default Escrow Account configuration
Serasa credit check	`CREDIT_BUREAU`	Perform credit check
Serasa negative credit reporting	`PAYMENT_DUNNING`	Create negative credit reporting
Tax information	`FISCAL_INFO`	Create or update tax information
Invoices	`INVOICE`	Schedule invoice
QR Code payment	`PIX_DEBIT`	Pay a QR Code
Pix key management	`PIX_ADDRESS_KEY`	Create a Pix key
Recurrence management	`PIX_RECURRING`	Cancel a recurrence
Pix transactions	`PIX_TRANSACTION`	List transactions
Automatic Pix	`PIX_AUTOMATIC`	Create Automatic Pix authorization
Transfers	`TRANSFER`	Make a transfer
Bill payment	`BILL`	Create bill payment
Mobile phone top-up	`MOBILE_PHONE_RECHARGE`	Request top-up
Statement and financial information	`FINANCIAL_TRANSACTION`	Retrieve statement
Account information	`ACCOUNT_INFO`	Update business data
Invoice page information	`PAYMENT_CHECKOUT_CONFIG`	Customize invoice page
Webhooks	`WEBHOOK`	Create new Webhook
Subaccounts	`SUB_ACCOUNT`	Create subaccount
Account documents	`ACCOUNT_DOCUMENT`	Send documents

Next steps

Updated 2 days ago

Did this page help you?