Skip to main content
As chaves de API autenticam as solicitações à API Pública do /v1. Cada chave pertence a uma conta de serviço e é criada a partir da página de detalhes dessa conta no Developer Hub. Utilize uma chave de API com escopo definido para uma integração de backend privada quando o armazenamento seguro e a rotação de um segredo atenderem aos seus requisitos. Não é necessário um cliente OAuth nem a troca de tokens. Consulte Autenticação se a sua organização exigir tokens de acesso OAuth de curta duração.

​
Anatomia de uma chave

  • Identificador — começa com ak_. Pode ser referenciado com segurança em tickets, logs e configurações; por si só, não concede nenhum acesso.
  • Segredo — começa com lsk_live_. Esta é a credencial que a sua integração apresenta. Ele é exibido uma única vez, na criação ou na rotação, e não pode ser recuperado posteriormente. A lista de chaves exibe apenas os quatro últimos caracteres (por exemplo, lsk_live_…xQc4) para que você possa associar uma linha à credencial que um solicitante possui.
  • Permissões — um subconjunto das permissões da conta de serviço proprietária, escolhido na criação. Uma chave nunca pode fazer mais do que a sua conta permite.
  • Expiração — obrigatória. Toda chave tem uma data de expiração.
Armazene os segredos em um gerenciador de segredos assim que forem exibidos. Nunca os inclua em um controle de versão, nem os incorpore em código do lado do cliente ou os compartilhe em chats. Qualquer pessoa que possua o segredo pode agir com as permissões da chave.

​
Criar uma chave

Na página de detalhes da conta de serviço, crie uma chave seguindo quatro etapas: atribua um nome, selecione as permissões de que esta chave específica necessita, escolha uma expiração — 30, 90 ou 365 dias, ou um período personalizado de até um ano — e revise. O segredo é exibido ao concluir, uma única vez. Limite o escopo de cada chave ao conjunto mínimo de permissões de que o seu solicitante necessita, mesmo quando a conta permitir mais. Se uma chave vazar, as suas permissões definem o alcance do impacto.

​
Rotação sem tempo de inatividade

A rotação emite um novo segredo e inicia uma janela de sobreposição — de 1 hora, 24 horas ou 7 dias — durante a qual o segredo antigo continua funcionando. Isso permite distribuir o novo segredo pelas suas implantações no seu próprio ritmo:
1

Faça a rotação da chave

Escolha uma janela de sobreposição que abranja o seu fluxo de implantação mais lento. O novo segredo é exibido uma única vez — armazene-o imediatamente.
2

Atualize as suas Integrações

Substitua o segredo antigo em todos os locais em que ele estiver configurado. O status da chave é exibido como em sobreposição até o fim da janela.
3

Verifique antes do encerramento da janela

Utilize os logs de solicitações para confirmar que o tráfego passou a usar o novo segredo. Quando a sobreposição terminar, o segredo antigo deixará de autenticar.
Faça a rotação também antes da expiração: as chaves que se aproximam da data de expiração são sinalizadas como prestes a expirar na lista de chaves. Uma chave expirada deixa de autenticar — as solicitações feitas com ela retornam um 401 com o código credential_expired.

​
Revogação imediata

A revogação entra em vigor imediatamente e é permanente — não há janela de sobreposição nem como desfazê-la. Revogue uma chave assim que suspeitar que o seu segredo foi exposto; em vez disso, faça a rotação quando estiver substituindo uma credencial íntegra. As solicitações feitas com uma chave revogada retornam um 401 com o código credential_revoked. Se precisar interromper de uma só vez todas as chaves que uma integração possui, desative a conta de serviço correspondente.