Skip to Content
ConfiguraçãoChaves de API

Chaves de API

Crie, gerencie e proteja chaves de API para autenticação com o SpecForge.

Chaves de API autenticam a CLI, o servidor MCP e quaisquer chamadas diretas de API ao seu projeto SpecForge. Toda requisição ao SpecForge deve incluir uma chave válida.

Criando uma Chave de API

  1. Abra seu projeto no painel do SpecForge
  2. Navegue até Settings > API Keys
  3. Clique em Generate New Key
  4. Dê à chave um rótulo descritivo (ex.: “Local Development”, “CI Pipeline”)
  5. Copie a chave imediatamente

⚠️ Chaves de API são exibidas apenas uma vez na criação. Se você perder uma chave, revogue-a e gere uma nova.

Formato da Chave

Toda chave do SpecForge carrega o prefixo sf_live_:

PrefixoPropósito
sf_live_Acesso completo aos dados e especificações do seu projeto

sf_live_ é o único formato de chave que o SpecForge emite, e o único que a API aceita — qualquer token sem esse prefixo é rejeitado na autenticação.

Usando Sua Chave de API

Opção 1: Login pelo Navegador (recomendado para dev local)

specforge login

Abre um fluxo de autenticação baseado em navegador e armazena credenciais em ~/.specforge/config.json automaticamente. Mais simples para desenvolvimento do dia a dia.

Opção 2: Flag de Chave de API (ambientes headless)

specforge login --api-key sf_live_...

Use para servidores remotos, pipelines de CI, ou qualquer ambiente sem navegador.

Opção 3: Variável de Ambiente (CI/CD)

export SPECFORGE_API_KEY="sf_live_..."

Abordagem recomendada para pipelines de CI/CD e ambientes containerizados. Armazene como secret no seu provedor de CI (GitHub Actions secrets, variáveis do GitLab CI, etc.).

Precedência

A chave de API resolve a partir de exatamente duas fontes, da mais específica para a menos:

  1. Variável de ambiente SPECFORGE_API_KEY (mais alta)
  2. Config global ~/.specforge/config.json (mais baixa)

Não existe um nível de chave por projeto: a chave nunca é lida do .specforge/config.json de um projeto. Isso significa que você pode manter uma chave padrão para desenvolvimento local na sua config global e sobrescrever por pipeline com uma variável de ambiente.

Gerenciando Chaves

Rotação

Para rotacionar uma chave sem downtime:

  1. Gere uma nova chave em Settings > API Keys
  2. Atualize sua config da CLI ou variável de ambiente com a nova chave
  3. Verifique a conectividade com specforge doctor
  4. Revogue a chave antiga pelo painel

O intervalo entre os passos 1 e 4 é sua janela de rotação. Ambas as chaves funcionam simultaneamente até a antiga ser revogada.

Revogação

Clique em Revoke ao lado de qualquer chave em Settings > API Keys. A revogação é imediata — qualquer requisição usando aquela chave falha com erro de autenticação a partir daquele momento.

Múltiplas Chaves

Crie quantas chaves precisar por projeto. Padrões comuns:

  • Uma chave por desenvolvedor para desenvolvimento local — se alguém sai, revogue a chave sem afetar outros
  • Chave dedicada de CI para pipelines — isolada das chaves de dev, fácil de rotacionar
  • Chaves separadas por ambiente de deploy — staging e produção usam chaves diferentes

Práticas de Segurança

  • Nunca commite chaves de API no controle de versão. Adicione ~/.specforge/config.json ao seu gitignore global ou use variáveis de ambiente exclusivamente.
  • Rotacione chaves periodicamente. Se uma chave pode ter sido exposta, revogue-a imediatamente e gere uma substituta.
  • Escopifique chaves ao seu propósito. Chaves separadas para CI, dev local e produção facilita revogar uma chave comprometida sem interromper outros fluxos de trabalho.
  • Use variáveis de ambiente no CI. Armazene chaves como secrets no seu provedor de CI, nunca em arquivos de configuração que serão commitados.

✅ Execute specforge doctor após qualquer mudança de chave para verificar se a autenticação está funcionando corretamente.

Veja Também

Padrões de QualidadeGestão de Equipe