API Keys

As chaves de API autenticam as suas requisições ao gateway da Retrace. Cada chave é única e deve ser mantida em um local seguro. Opcionalmente, você pode definir um teto de gasto para cada chave, junto com um período de reset.

Criar uma chave

Crie uma chave de API para sua aplicação através do painel da Retrace.

1. Acesse a página API Keys e clique em Adicionar chave.
2. Dê um nome para a sua chave e clique em Criar chave.
3. Copie a chave gerada e guarde-a em um local seguro, como uma variável de ambiente RETRACE_API_KEY.

O valor da chave só é exibido uma única vez, no momento da criação. Se você perder o valor, não é possível recuperá-lo — nesse caso, rotacione a chave para gerar um novo valor.

Limite de crédito

Você pode definir um teto de gasto (em reais) para cada chave de API. O limite é individual por chave — não é compartilhado entre outras chaves do mesmo workspace — e pode ser alterado a qualquer momento na página da chave. Se nenhum limite for definido, a chave pode ser usada sem restrição de gasto.

Quando o consumo de uma chave atinge o limite definido, a Retrace bloqueia novas requisições feitas com essa chave imediatamente, retornando o erro credit_limit_exceeded. Não há tolerância ou período de carência: o bloqueio entra em vigor assim que o limite é atingido, e só é removido em um reset — automático ou manual.

Período de reset

Junto com o limite de crédito, você pode definir um período de reset, que determina de quanto em quanto tempo o consumo da chave volta a zero automaticamente. As opções disponíveis são:

• Nenhum: o consumo não é resetado automaticamente e acumula durante toda a vida da chave.
• Diário: o consumo volta a zero todos os dias.
• Semanal: o consumo volta a zero a cada semana.
• Mensal: o consumo volta a zero a cada mês.

A contagem do período começa na criação da chave (ou na última alteração do período de reset) e se repete automaticamente a partir daí. A data do próximo reset fica visível na página da chave.

Zerar consumo

Se quiser reiniciar o consumo de uma chave antes do próximo reset automático, você pode zerar o consumo manualmente a qualquer momento.

1. Acesse a página API Keys.
2. Selecione a chave desejada e clique em Zerar consumo.
3. Confirme a ação.

Essa ação zera o contador de consumo atual e reinicia a contagem do período de reset a partir daquele momento — o histórico de uso da chave não é apagado. Se a chave estava bloqueada por ter atingido o limite de crédito, ela volta a funcionar imediatamente.

Rotacionar chave

Rotacionar uma chave gera um novo valor para ela, mantendo as demais configurações (limite de crédito, período de reset e histórico de uso).

1. Acesse a página API Keys.
2. Selecione a chave desejada e clique em Rotacionar chave.
3. Copie o novo valor exibido e guarde-o em um local seguro — ele não será mostrado novamente.

Use a rotação quando suspeitar que uma chave foi exposta, mas quiser manter as mesmas configurações e o mesmo histórico de uso.

Revogar chave

Revogar uma chave a desativa permanentemente. Diferente da rotação, uma chave revogada não pode ser reativada nem ter seu valor substituído — para continuar integrando, é necessário criar uma nova chave.

1. Acesse a página API Keys.
2. Selecione a chave desejada e clique em Revogar chave.
3. Confirme a ação.

Revogue uma chave quando ela não for mais necessária ou quando tiver certeza de que ela não deve mais ser usada — por exemplo, ao desligar uma integração.