Como Criar e Gerenciar Chaves de API de Desenvolvedor no FirstSales
Gere chaves de API com privilégio mínimo e escopos por recurso, use-as com a CLI e a API REST, e rotacione ou revogue com segurança sem causar interrupção.
- 1
Abra Configurações → API
As chaves de API ficam em Configurações → API. É aqui que você gera a credencial que autentica o CLI e qualquer chamada direta a
https://api.app.firstsales.io. Você precisa da permissão certa para ver essa aba. - 2
Crie uma chave com escopos de privilégio mínimo
Clique para criar uma chave, dê a ela um nome (algo que indique onde é usada, ex.: "ci-contact-sync"), e marque apenas os escopos que ela precisa. Escopos são por recurso e separam leitura de escrita — ex.:
contacts:read,contacts:write,campaigns:read,kb:read. Há um escopo*que concede tudo; evite-o a menos que você realmente precise de acesso total.
- 3
Copie a chave imediatamente
A chave completa é exibida exatamente uma vez — "Copie esta chave agora. Ela não será mostrada novamente." Copie-a diretamente para seu cofre de segredos ou gerenciador de senhas. Se você a perder, não poderá recuperá-la; você revoga e cria uma nova. Nunca cole em código, chat ou commit.
- 4
Use-a com o CLI
Exporte a chave como
FIRSTSALES_API_KEYe o CLI a detecta automaticamente. Verifique comwhoamiantes de fazer qualquer outra coisa:export FIRSTSALES_API_KEY="fs_live_..." # do seu cofre de segredos, nunca fixo no código firstsales whoami --json - 5
Use-a diretamente com a API
Para HTTP puro, envie a chave como um token Bearer. Comece com
whoamipara confirmar que a chave é válida e ler qual org/workspace ela alcança:curl -s https://api.app.firstsales.io/api/v1/whoami \ -H "Authorization: Bearer $FIRSTSALES_API_KEY" - 6
Rotacione e revogue
Cada chave na lista pode ser revogada, e a revogação é imediata e sem desfazer — qualquer CLI ou serviço usando-a falha na próxima chamada. Para rotacionar: crie a nova chave, implante-a no seu cofre de segredos, confirme que a nova funciona, depois revogue a antiga. Revogue instantaneamente se uma chave for exposta.
Dicas de especialista
Atalhos conquistados na prática que mantêm o aquecimento nos trilhos.
Uma chave por consumidor
Dê ao CI, ao seu laptop e a cada integração sua própria chave nomeada. Quando uma vaza ou um serviço é desativado, você revoga só aquela chave em vez de quebrar tudo.
Privilégio mínimo vence conveniência
Uma sincronização somente leitura não precisa de contacts:write, e quase nada precisa de `*`. Restrinja o escopo — uma chave somente leitura vazada não consegue alterar seus dados.
Copie uma vez, guarde em um gerenciador de segredos
A chave é mostrada uma única vez. Cole diretamente no seu cofre de segredos do CI ou gerenciador de senhas — nunca no código-fonte, em um .env que você possa commitar, ou em uma mensagem de chat.
Rotacione com sobreposição, não com lacuna
Crie-implante-verifique-depois revogue. Revogar antes que a substituta esteja ativa causa uma indisponibilidade; a janela de sobreposição mantém as chamadas fluindo durante a rotação.
Perguntas frequentes
Onde crio uma chave de API?
Configurações → API. Dê um nome, marque os escopos necessários e crie. A chave autentica tanto o CLI quanto chamadas diretas à API.
O que são escopos?
Permissões por recurso, separadas em leitura e escrita — ex.: contacts:read, campaigns:write, kb:read, além de um * que concede tudo. Marque apenas o que o consumidor da chave precisa.
Perdi minha chave — posso vê-la de novo?
Não. A chave completa é exibida uma vez na criação (“Ela não será mostrada novamente”). Se você a perder, revogue aquela chave e crie uma nova.
Como o CLI usa a chave?
Defina-a como a variável de ambiente FIRSTSALES_API_KEY; o CLI a lê automaticamente. Execute firstsales whoami para confirmar que funciona.
Como revogo uma chave?
Na lista de configurações de API, revogue-a. A revogação é imediata e permanente — qualquer coisa usando aquela chave falha na próxima chamada, então rotacione uma substituta antes.
Como devo rotacionar chaves com segurança?
Crie a nova chave, implante-a, confirme que funciona, depois revogue a antiga. Essa sobreposição evita uma indisponibilidade. Revogue imediatamente (sem sobreposição) apenas se uma chave for exposta.
Pronto para colocar isso em prática?
Comece seu teste do FirstSales e lance uma caixa de e-mail aquecida e autenticada em minutos.
Comece por $1