Endpoint responsável por atualizar as configurações de uma chave de API já existente em uma subconta Asaas.

Com este endpoint, a conta-pai pode alterar informações de uma chave de API da subconta, como nome, status de habilitação e data de expiração, sem precisar acessar manualmente a subconta pela interface Web.

Essa funcionalidade faz parte do gerenciamento de chaves de API de subcontas e é indicada para operações que precisam controlar o ciclo de vida das credenciais de forma centralizada e segura.

Quando utilizar este endpoint

Utilize este endpoint quando sua integração precisar:

• renomear uma chave de API de uma subconta;
• habilitar uma chave previamente desabilitada;
• desabilitar temporariamente uma chave sem excluí-la;
• alterar a data de expiração de uma chave existente;
• padronizar nomes de chaves utilizadas por sistemas internos;
• executar rotação ou manutenção de credenciais de subcontas;
• corrigir uma chave criada com nome ou expiração incorreta;
• controlar o acesso de integrações vinculadas a subcontas.

Esse endpoint é especialmente útil para parceiros, plataformas White Label, marketplaces, ERPs e operações BaaS que gerenciam múltiplas subcontas e precisam manter as credenciais organizadas e seguras.

Quando não utilizar

Não utilize este endpoint para:

• criar uma nova chave de API;
• excluir ou revogar definitivamente uma chave;
• listar chaves existentes de uma subconta;
• atualizar dados cadastrais da subconta;
• alterar permissões de uma chave fora dos campos aceitos;
• recuperar o valor da chave de API já criada.

Caso precise criar uma nova chave, utilize o endpoint de criação de chave de API para subconta.

Caso precise remover definitivamente uma chave, utilize o endpoint de exclusão ou revogação de chave de API.

Requisitos de acesso

Por se tratar de uma operação sensível, este endpoint possui requisitos específicos de segurança.

Antes de chamar este endpoint, verifique se:

• a conta-pai possui subcontas vinculadas;
• o acesso ao gerenciamento de chaves de subcontas foi habilitado na interface Web;
• a chamada está sendo realizada dentro do período de liberação temporária;
• a Whitelist de IPs está habilitada;
• o IP de saída da sua aplicação está autorizado;
• a requisição está autenticada com a chave de API da conta-pai;
• a subconta informada existe e pertence à conta-pai autenticada;
• o accessTokenId informado corresponde a uma chave de API existente da subconta.

Fluxo recomendado

Em uma integração típica, a atualização de chave de API de uma subconta deve seguir o fluxo abaixo:

Habilitar o acesso ao gerenciamento de chaves na interface Web
↓
Garantir que a Whitelist de IPs está habilitada
↓
Listar as chaves de API da subconta
↓
Identificar o accessTokenId da chave que será atualizada
↓
Montar o payload com name, enabled e expirationDate
↓
Enviar a atualização
↓
Validar a resposta da API
↓
Atualizar os controles internos da sua aplicação

A atualização depende do accessTokenId. Por isso, antes de chamar este endpoint, liste as chaves da subconta ou utilize o identificador retornado no momento da criação da chave.

Parâmetros de path

O parâmetro id deve corresponder à subconta vinculada à conta-pai autenticada.

O parâmetro accessTokenId deve corresponder a uma chave de API existente daquela subconta.

Parâmetros do body

name

Informe um nome que facilite a identificação da chave.

Exemplos:

Integração ERP
Integração Checkout
Rotação API - Julho 2026

enabled

Define se a chave ficará habilitada ou desabilitada.

Valores aceitos:

Desabilitar uma chave pode interromper integrações que dependem dela. Antes de alterar esse campo para false, confirme se a aplicação já está utilizando outra chave válida.

expirationDate

Define a data e hora de expiração da chave.

Utilize um formato de data e hora compatível com date-time.

Exemplo:

2026-12-31T23:59:59Z

Exemplo de requisição

curl --request PUT \
  --url https://api-sandbox.asaas.com/v3/accounts/acc_000000000001/accessTokens/atk_000000000001 \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --header 'access_token: $ASAAS_PARENT_API_KEY' \
  --data '{
    "name": "Integração ERP - Subconta",
    "enabled": true,
    "expirationDate": "2026-12-31T23:59:59Z"
  }'

Exemplo de resposta

{
  "id": "atk_000000000001",
  "name": "Integração ERP - Subconta",
  "enabled": true,
  "expirationDate": "2026-12-31T23:59:59Z"
}

Comportamento da atualização

Ao atualizar uma chave de API de uma subconta:

• a chave permanece associada à mesma subconta;
• o identificador da chave não é alterado;
• o valor secreto da chave não é retornado novamente;
• o endpoint altera apenas os campos enviados no body aceito pela rota;
• alterações no campo enabled podem afetar imediatamente integrações que utilizam a chave;
• alterações em expirationDate modificam o ciclo de vida da chave;
• a atualização não cria uma nova chave;
• a atualização não revoga definitivamente a chave.

A chave de API do Asaas é irrecuperável após a criação. Por isso, este endpoint não deve ser usado para tentar consultar o valor secreto da credencial.

Regras de negócio importantes

Ao utilizar este endpoint, considere que:

• a chamada deve ser feita pela conta-pai;
• a subconta deve pertencer à conta-pai autenticada;
• o accessTokenId deve pertencer à subconta informada;
• o acesso aos endpoints de gerenciamento deve estar habilitado na interface Web;
• a liberação do acesso é temporária;
• a Whitelist de IPs deve estar habilitada;
• o IP de origem da requisição deve estar autorizado;
• name, enabled e expirationDate são obrigatórios no body;
• desabilitar uma chave pode interromper integrações em uso;
• excluir uma chave é diferente de desabilitar uma chave;
• uma chave excluída não pode ser restaurada.

Diferença entre atualizar, desabilitar e excluir

Cuidados em operações de rotação de chave

Em cenários de rotação de chave, evite desabilitar a chave antiga antes de confirmar que a nova chave já está em uso pela aplicação.

Fluxo recomendado:

Criar nova chave para a subconta
↓
Armazenar a nova chave com segurança
↓
Atualizar a aplicação para usar a nova chave
↓
Validar chamadas com a nova chave
↓
Desabilitar a chave antiga
↓
Monitorar erros de autenticação
↓
Excluir a chave antiga somente quando não houver mais dependência

Esse cuidado reduz o risco de indisponibilidade em integrações que dependem da subconta.

Erros comuns

Alguns erros comuns ao utilizar este endpoint incluem:

Impactos operacionais

A atualização de uma chave de API pode impactar diretamente a disponibilidade da integração da subconta.

Configurações incorretas podem causar:

• interrupção de chamadas autenticadas;
• falhas 401 Unauthorized;
• perda temporária de comunicação entre sua aplicação e a subconta;
• expiração inesperada de credenciais;
• dificuldade de rastrear qual sistema utiliza cada chave;
• necessidade de rotação emergencial;
• falhas em fluxos de cobrança, consulta, webhook ou onboarding que dependam da chave atualizada.

Por isso, trate a atualização de chaves como uma operação sensível e registre logs internos de alteração.

Boas práticas

Ao atualizar chaves de API de subcontas, recomenda-se:

• utilizar nomes descritivos para cada chave;
• manter inventário interno de quais sistemas utilizam cada chave;
• evitar desabilitar uma chave sem confirmar que ela não está mais em uso;
• planejar janelas de manutenção para alterações críticas;
• validar a nova configuração em Sandbox antes de aplicar em Produção;
• armazenar chaves em gerenciadores de segredo;
• monitorar erros 401 após alterações;
• manter a Whitelist de IPs restrita ao menor conjunto possível de endereços;
• evitar intervalos amplos de IPs;
• registrar usuário, sistema, data e motivo da atualização;
• utilizar webhooks de ciclo de vida de chaves, quando aplicável.

Cuidados em Sandbox

Este endpoint pode ser testado em Sandbox.

Recomenda-se validar os seguintes cenários:

• listar chaves de API de uma subconta;
• atualizar o nome de uma chave;
• alterar enabled para false;
• tentar utilizar uma chave desabilitada;
• alterar enabled para true;
• atualizar a data de expiração;
• testar uma chamada com IP não autorizado;
• testar o comportamento após expiração da liberação temporária.

Esses testes ajudam a definir o comportamento esperado antes da operação em Produção.

Conteúdos relacionados

Consulte também:

• Gerenciamento das chaves de API de subcontas;
• Listar chaves de API de uma subconta;
• Criar chave de API para uma subconta;
• Excluir chave de API de uma subconta;
• Chaves de API;
• Whitelist de IPs;
• Criação de subcontas;
• Autenticação;
• O que pode ser testado em Sandbox.