Gerenciamento de permissões de Chaves de API

O sistema de permissões de chaves de API do Asaas permite que você defina, com granularidade, quais recursos e ações uma chave específica pode acessar. Adotar o princípio do menor privilégio aumenta a segurança da sua integração, garantindo que, em caso de vazamento de uma credencial, o impacto seja limitado apenas aos escopos configurados.

Como funciona?

Ao criar ou editar uma chave de API (seja pela interface web ou via API para subcontas), você pode definir um array de permissions. Cada permissão é composta por:

name: O recurso a ser acessado (ex: PAYMENT, TRANSFER).

scope: O nível de acesso permitido.

READ: Permite apenas leitura (GET).

READ_WRITE: Permite leitura (GET) e ações de escrita (POST, PUT, DELETE).

📘

Recomendação de segurança e boas práticas

• Atualmente, se o objeto accessTokenConfig ou o array de permissions não forem enviados na criação, o sistema gerará uma chave com todas as permissões habilitadas no escopo READ_WRITE.
• Para garantir maior segurança na sua integração e minimizar riscos em casos de vazamento de credenciais, recomendamos fortemente que novas integrações já sejam construídas enviando as permissões restritas (princípio do menor privilégio).
• Embora o envio do objeto permissions seja atualmente opcional, prevê-se que essa definição se torne obrigatória em atualizações futuras. Adotar esse padrão agora garante que sua integração já esteja preparada para os próximos requisitos de segurança do Asaas.

Criando uma chave com permissões (Via API)

Ao criar uma subconta você deve enviar o objeto accessTokenConfig.

Endpoint: POST /v3/accounts

Exemplo de Request:

{
  "name": "Subconta Integrada",
  "email": "[email protected]",
  "cpfCnpj": "12345678000199",
  "...": "...",
  "accessTokenConfig": {
     "name": "Chave de Integração Financeira",
     "permissions": [
        {
            "name": "PAYMENT",
            "scope": "READ_WRITE"
        },
        {
            "name": "TRANSFER",
            "scope": "READ"
        },
        {
            "name": "WEBHOOK",
            "scope": "READ_WRITE"
        }
     ] 
  }
}

Exemplo de Response:

{
    "object": "account",
    "id": "8de2fa50-589e-4a95-a545-e6bd6e1ed71a",
    "...": "...",
    "accessToken": {
        "id": "3e9d4210-4948-4829-a0f0-c06b69ce2fa3",
        "name": "Chave de Integração Financeira",
        "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"
    }
}

Gerenciamento de chaves existentes

Você também pode atualizar as permissões de chaves já existentes em suas subcontas para aumentar a segurança de integrações legadas. Utilize os endpoints detalhados na seção Gerenciamento de Chaves de API de Subcontas.

👍

Nesses endpoints envie apenas o array permissions.

Tratamento de erros

Caso uma chave tente acessar um endpoint para o qual não possui permissão (ex: tentar criar uma transferência usando uma chave que tem apenas TRANSFER: READ ou que não possui a permissão TRANSFER), a API retornará um erro HTTP 403 Forbidden.

Exemplo de erro:

{
    "errors": [
        {
            "code": "insufficient_permission",
            "description": "A chave de API fornecida não tem as permissões necessárias. Verifique se a chave possui o escopo FINANCIAL_TRANSACTION:READ para acessar o recurso solicitado"
        }
    ]
}

Tabela de referência de permissões

Abaixo, listamos a correlação entre os módulos apresentados na Interface do Asaas e os nomes técnicos das permissões via API.