API: credenciais — criar chaves com nome e validade, revogar, e o segredo que aparece uma vez só

Uma chave de API é como uma senha que você entrega a um programa (uma integração, uma automação ou um sistema seu) para ele acessar a sua conta automaticamente. Você dá um nome a cada chave, define por quanto tempo ela vale e pode revogar quando quiser. A sua conta pode ter várias chaves ao mesmo tempo, uma para cada integração.

Cada chave é um par de códigos: o Access Token e o Secret Access Token. É esse par que a integração envia em toda chamada.

Caminho

Meus aplicativos › Ver todos os aplicativos › API (botão Acessar)

Dentro do aplicativo, clique no cartão Credenciais da tela inicial, ou no item Credenciais do menu lateral. O menu lateral tem também o item MCP, para conectar um assistente de IA, explicado em outro artigo.

Só o usuário master da conta entra nessa tela. Para os demais usuários aparece a mensagem "Somente o usuário master tem acesso às chaves de API."

A lista de chaves

A tela mostra todas as chaves da conta, com estas colunas:

  • Nome — o nome que você deu ao criar. Chave criada antes de existir o nome aparece com um traço.
  • Access Token — o código público da chave.
  • Criada por — o usuário que criou.
  • Criada em — data e hora da criação.
  • Último uso — a última vez em que a integração usou a chave. Chave que nunca foi usada mostra "Nunca usada".
  • Expira em — a data de vencimento, ou "Nunca". Chave vencida aparece em vermelho, com "(expirada)" ao lado.
  • Ações — o botão de revogar.

O campo Buscar filtra a lista pelo nome, por quem criou ou pelo Access Token.

Criar uma chave

1. Clique em Nova chave.
2. Informe o Nome. É obrigatório e aceita até 80 caracteres. Use algo que identifique a integração, como "Integração loja virtual".
3. Escolha a Validade: Nunca expira, 30 dias, 60 dias, 90 dias, 6 meses ou 1 ano. O padrão é Nunca expira. A validade é definida agora e não muda depois.
4. Clique em Criar chave.

A janela "Chave criada" mostra o Access Token e o Secret Access Token, cada um com o botão de copiar. Preste atenção ao aviso: o Secret Access Token é exibido apenas uma vez. Ao fechar a janela, ele não será mostrado novamente. Se perder, crie outra chave.

O botão Baixar credenciais gera um arquivo de texto com o nome da chave e os dois códigos, para você guardar em local seguro. Clique em Concluído quando terminar.

Criar uma chave nova não mexe nas outras. As chaves que já existiam continuam funcionando normalmente.

Revogar uma chave

Na linha da chave, clique no botão Revogar e confirme. A chave deixa de funcionar imediatamente e não pode ser recuperada.

Revogar afeta só aquela chave. As demais seguem valendo. A integração que ainda usar a chave revogada passa a receber "Access Token e/ou Secret Access Token incorreto(s)!".

Antes de revogar, avise quem depende daquela chave. Quem esquece disso derruba a própria integração no mesmo minuto.

Validade e vencimento

Quando a data de Expira em passa, a chave para de funcionar sozinha e a integração recebe "Token expirado!". A lista marca a chave como expirada.

Não existe renovar nem estender a validade de uma chave. O caminho é criar outra chave, trocar o par na integração e, se quiser limpar a lista, revogar a vencida.

O que mudou em relação ao token único

Antes a conta tinha um token só, e o botão Gerar token trocava o par: o anterior parava de valer na hora. Agora:

  • A conta tem quantas chaves precisar, cada uma com nome e validade.
  • Criar chave nova não invalida nenhuma outra.
  • Só revogar (ou o vencimento) tira uma chave de uso.
  • O token gerado antes dessa mudança continua valendo. Ele aparece na lista sem nome e com validade "Nunca".

Quando dá errado

  • "Somente o usuário master tem acesso às chaves de API." — só o usuário master da conta cria, vê e revoga chaves. Peça a ele.
  • "O seu plano atual não lhe permite integrar com a API. Por favor, contrate outro plano!" — a integração por API não está liberada na conta. Em Meus aplicativos › Ver todos os aplicativos, veja o que o cartão da API mostra: Testar grátis liga na hora por 7 dias; se mostrar Acessar e mesmo assim não abrir, é caso de contratação com quem cuida do plano.
  • "Informe um nome para a chave." — o nome é obrigatório.
  • Perdi o Secret Access Token — não há como ver de novo. Crie outra chave e atualize a integração.
  • "Token expirado!" na integração — a chave venceu. Crie outra chave.
  • "Access Token e/ou Secret Access Token incorreto(s)!" logo depois de revogar — é o esperado: a chave revogada não vale mais. A integração precisa do par de uma chave ativa.
  • Não encontro o botão Gerar token — ele não existe mais. Use Nova chave.