Skip to main content
Chaves de API são a forma como sistemas e scripts externos se autenticam na API REST pública do Switchbord sem uma sessão de login interativa. As chaves têm o escopo do workspace — uma chave só pode ver e operar no workspace em que foi criada — e são exibidas por completo exatamente uma vez, no momento da criação.

​
Onde gerenciar as chaves

Vá para Settings → Integrations → API Keys. Criar, revogar e excluir chaves exige o papel owner ou admin no workspace; qualquer membro do workspace pode visualizar a lista de chaves existentes (apenas pelo nome e prefixo — nunca o segredo completo).

​
Criando uma chave

  1. Clique em Create key.
  2. Dê um nome descritivo a ela (ex.: “Integração de produção”, “Sincronização Zapier”).
  3. Escolha um escopo (veja abaixo).
  4. Opcionalmente, defina uma validade — Never, 30 dias, 90 dias ou 1 ano.
  5. Clique em Create key. A chave completa é exibida uma vez em uma janela — copie-a imediatamente. O Switchbord armazena apenas um hash SHA-256 e um prefixo de 8 caracteres para exibição; o segredo bruto não pode ser recuperado depois disso.
Se você perder uma chave, não há como recuperá-la novamente — revogue-a e crie uma nova. Nunca cole uma chave ativa em código do lado do cliente, em um arquivo versionado ou em uma mensagem de chat.

​
Formato da chave

As chaves geradas têm o prefixo swb_ (algumas ferramentas legadas de provisionamento e scripts internos ainda geram chaves com prefixo sk_live_ para fins de bootstrap — ambos os formatos são validados da mesma forma). O prefixo torna as chaves fáceis de identificar em logs e diffs, e permite que ferramentas automatizadas de varredura de segredos detectem rapidamente uma chave commitada por acidente.

​
Escopos

Toda chave é criada com exatamente um escopo, que delimita o que ela pode fazer independentemente de qual endpoint ela chama: Escolha o escopo mais restrito que atenda à necessidade — um script que só precisa ler contatos não deve ter uma chave management.

​
Autenticando requisições

Passe a chave como um Bearer token:
O Switchbord resolve o workspace da chamada diretamente a partir da chave — nunca envie um ID de workspace no corpo da requisição esperando que ele seja confiável. Em cada requisição, o hash da chave é consultado, verificado em relação ao seu escopo e expiração, e last_used_at é atualizado.

​
Revogando e excluindo

  • Revoke invalida imediatamente uma chave para autenticação, mantendo seu registro (e histórico de uso) visível na lista, marcado como revogado.
  • Delete remove o registro da chave por completo.
Toda ação de criação, revogação e exclusão é registrada no log de auditoria do workspace, então você sempre pode responder “quem emitiu esta chave e quando”.

​
Expiração

As chaves podem ser configuradas para nunca expirar, ou para expirar automaticamente após 30 dias, 90 dias ou 1 ano. Uma chave expirada falha na autenticação da mesma forma que uma revogada — as requisições retornam 403 em vez de ter sucesso silenciosamente.

​
Veja também