Gerenciamento de permissões de Chaves de API

Defina quais recursos e ações cada chave de API pode acessar.

Utilizar somente as permissões necessárias reduz o impacto caso uma credencial seja comprometida.

📘
Ao concluir este guia, você saberá configurar permissões ao criar ou atualizar uma chave de API.

Como funcionam as permissões

Ao criar ou editar uma chave pela interface web, ou pela API no caso de subcontas, defina o array permissions.

Cada item contém:

Campo	Descrição	Exemplo
`name`	Recurso que poderá ser acessado	`PAYMENT`, `TRANSFER`
`scope`	Nível de acesso permitido	`READ`, `READ_WRITE`

Os escopos disponíveis são:

Escopo	Acesso
`READ`	Permite operações de leitura, como `GET`
`READ_WRITE`	Permite leitura e operações de escrita, como `POST`, `PUT` e `DELETE`

⚠️
Defina as permissões explicitamente
Caso accessTokenConfig ou permissions não sejam enviados, a chave será criada com todas as permissões no escopo READ_WRITE.
Recomendamos aplicar o princípio do menor privilégio e liberar somente os recursos necessários para a integração.
A definição das permissões poderá se tornar obrigatória em atualizações futuras.

Crie uma chave com permissões

Ao criar uma subconta, envie o objeto accessTokenConfig.

Endpoint

POST /v3/accounts

Exemplo de requisição

{
  "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"
      }
    ]
  }
}

Nesse exemplo, a chave poderá:

consultar e gerenciar cobranças;
consultar transferências, sem criá-las ou alterá-las;
consultar e gerenciar Webhooks.

Exemplo de resposta

{
  "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"
  }
}

Confira o objeto accessToken.permissions para confirmar as permissões atribuídas à chave.

Atualize uma chave existente

Também é possível alterar as permissões das chaves de API de subcontas já existentes.

Consulte Gerenciamento de chaves de API de subcontas.

📘
Nos endpoints de atualização, envie no body somente o array permissions.

Erro por permissão insuficiente

Quando uma chave tenta acessar um recurso sem a permissão necessária, a API retorna 403 Forbidden.

Exemplo:

{
  "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"
    }
  ]
}

Para corrigir:

identifique a permissão informada na mensagem;
confira as permissões atuais da chave;
atualize o escopo ou utilize outra chave autorizada;
evite liberar permissões que não sejam necessárias.

Permissões disponíveis

A tabela abaixo relaciona os recursos exibidos na interface do Asaas com os nomes utilizados pela API.

Recurso	Permissão	Endpoint relacionado
Clientes	`CUSTOMER`	Criar novo cliente
Notificações	`CUSTOMER_NOTIFICATION`	Atualizar notificações em lote
Cobranças	`PAYMENT`	Criar nova cobrança
Estornos de cobranças	`PAYMENT_REFUND`	Estornar cobrança
Chargeback	`CHARGEBACK`	Criar disputa de chargeback
Parcelamentos	`INSTALLMENT`	Criar parcelamento
Assinaturas	`SUBSCRIPTION`	Criar nova assinatura
QR Code estático	`PIX_CREDIT`	Criar QR Code estático
Link de pagamento	`PAYMENT_LINK`	Criar link de pagamento
Checkout	`CHECKOUT`	Criar novo Checkout
Cartão de crédito	`CREDIT_CARD`	Tokenizar cartão de crédito
Antecipações	`ANTICIPATION`	Solicitar antecipação
Configurações de antecipações	`ANTICIPATION_CONFIG`	Atualizar antecipação automática
Garantia de cobranças	`ESCROW`	Encerrar garantia da cobrança
Configuração da conta Escrow	`ESCROW_CONFIG`	Criar configuração padrão da conta Escrow
Consulta Serasa	`CREDIT_BUREAU`	Realizar consulta
Negativação Serasa	`PAYMENT_DUNNING`	Criar negativação
Informações fiscais	`FISCAL_INFO`	Criar ou atualizar informações fiscais
Notas fiscais	`INVOICE`	Agendar nota fiscal
Pagamento de QR Codes	`PIX_DEBIT`	Pagar um QR Code
Gerenciamento de chaves Pix	`PIX_ADDRESS_KEY`	Criar uma chave Pix
Gerenciamento de recorrências	`PIX_RECURRING`	Cancelar uma recorrência
Transações Pix	`PIX_TRANSACTION`	Listar transações
Pix Automático	`PIX_AUTOMATIC`	Criar autorização Pix Automático
Transferências	`TRANSFER`	Realizar transferência
Pagamento de contas	`BILL`	Criar pagamento de conta
Recarga de celular	`MOBILE_PHONE_RECHARGE`	Solicitar recarga
Extrato e informações financeiras	`FINANCIAL_TRANSACTION`	Consultar extrato
Informações da conta	`ACCOUNT_INFO`	Atualizar dados comerciais
Informações da fatura	`PAYMENT_CHECKOUT_CONFIG`	Personalizar fatura
Webhooks	`WEBHOOK`	Criar novo Webhook
Subcontas	`SUB_ACCOUNT`	Criar subconta
Documentos de contas	`ACCOUNT_DOCUMENT`	Enviar documentos

Próximos passos

Updated 3 months ago

Did this page help you?