Gerenciamento das chaves de API de subcontas

Em operações BaaS, a conta-pai pode criar, listar, atualizar e excluir chaves de API das suas subcontas sem acessar individualmente cada conta.

Use esse fluxo para realizar rotação de credenciais, substituir uma chave perdida ou expirada e controlar o ciclo de vida das chaves utilizadas pelas integrações.

Uma chave já criada não pode ter seu valor recuperado. Se a credencial for perdida ou expirar, crie uma nova chave.

Antes de começar

Para utilizar os endpoints de gerenciamento:

• habilite temporariamente o acesso pela interface web do Asaas;
• mantenha a Whitelist de IPs habilitada;
• autorize o IP de saída utilizado pela sua aplicação;
• autentique as requisições com a chave de API da conta-pai;
• tenha o ID da subconta que será gerenciada.

Durante o Período de Avaliação, a apiKey da subconta é disponibilizada. Para continuar utilizando as chaves das subcontas após esse período, a operação deve estar adequada ao BaaS do Asaas ou enquadrada como subcontas de filiais com o mesmo prefixo de CNPJ da conta principal.

1. Habilite o gerenciamento de chaves

Os endpoints ficam bloqueados por padrão.

Na interface web do Asaas:

1. acesse Integrações > Chaves de API;
2. localize Gerenciamento de Chaves de API de Subcontas;
3. clique em Habilitar acesso.

Após as 2 horas, habilite novamente o acesso antes de realizar novas operações.

2. Escolha a operação

Todas as chamadas abaixo são autenticadas com a chave da conta-pai.

Listar chaves

Use a listagem para recuperar os IDs e as configurações das chaves da subconta.

O valor secreto de uma chave já criada não é retornado.

Armazene o accessTokenId quando precisar atualizar ou excluir uma chave.

Criar uma chave

Ao criar uma nova chave, informe o nome e a data de expiração conforme a API Reference.

A credencial é retornada apenas uma vez. Capture o access_token da resposta e armazene-o imediatamente em um gerenciador de segredos.

Não registre o valor em logs ou interfaces administrativas.

Atualizar uma chave

Utilize o accessTokenId para alterar configurações de uma chave existente, como:

• nome;
• status de habilitação;
• data de expiração.

Desabilitar uma chave com enabled: false interrompe a autenticação das integrações que ainda utilizam essa credencial.

Excluir uma chave

A exclusão revoga definitivamente a chave.

Não exclua uma credencial enquanto alguma aplicação ainda depender dela. Uma chave excluída não pode ser restaurada.

Faça a rotação sem interromper a integração

Quando precisar substituir uma credencial, mantenha a chave atual ativa até confirmar que a nova já está sendo utilizada.

%%{init: {"flowchart": {"nodeSpacing": 28,"rankSpacing": 32,"diagramPadding": 8,"padding": 10}}}%%
flowchart TD
    A["Criar nova chave"] --> B["Armazenar a credencial"]
    B --> C["Atualizar a aplicação"]
    C --> D["Validar autenticação"]
    D --> E["Desabilitar a chave antiga"]
    E --> F["Monitorar falhas"]
    F --> G["Excluir a chave antiga"]

    classDef inicio fill:#DBEAFE,stroke:#2563EB,color:#1E3A8A,stroke-width:3px,font-size:17px
    classDef validacao fill:#E0F2FE,stroke:#0284C7,color:#0C4A6E,stroke-width:2px,font-size:17px
    classDef sucesso fill:#DCFCE7,stroke:#16A34A,color:#14532D,stroke-width:3px,font-size:17px

    class A inicio
    class B,C,D,E,F validacao
    class G sucesso

    linkStyle default stroke:#94A3B8,stroke-width:2px

Esse fluxo também deve ser utilizado quando a chave original for substituída por expiração ou comprometimento.

Monitore o ciclo de vida das chaves

Utilize os Webhooks para chaves de API para acompanhar alterações sem realizar consultas recorrentes.

Os eventos permitem identificar criação, habilitação, desabilitação, exclusão e expiração de chaves.

Em subcontas BaaS, monitore especialmente ACCESS_TOKEN_EXPIRED: essas chaves não passam pela desabilitação automática após três meses de inatividade, mas continuam sujeitas à expiração permanente após seis meses.

Como validar o gerenciamento

Após executar uma operação:

1. liste as chaves da subconta para confirmar as configurações atuais;
2. ao criar uma chave, confirme que a credencial foi armazenada antes de descartar a resposta;
3. ao realizar uma rotação, valide chamadas autenticadas com a nova chave antes de desabilitar a anterior;
4. ao excluir uma chave, confirme previamente que nenhum sistema ainda depende dela.

Se receber 403 Forbidden, confirme se a liberação temporária ainda está ativa e se o IP da aplicação está autorizado na Whitelist.

Próximos passos

• Configure a Whitelist de IPs
• Conheça os eventos para chaves de API
• Crie e gerencie chaves de API
• Crie subcontas com o BaaS do Asaas
• Consulte a FAQ do Período de Avaliação