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

O SpecForge usa chaves com prefixo para que você identifique o ambiente com um olhar:

Chaves de teste operam contra uma cópia isolada do seu projeto. Mudanças feitas com uma chave de teste não afetam dados de produçã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

Quando múltiplas fontes fornecem uma chave de API, a mais específica vence:

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

Isso significa que você pode ter uma chave padrão para desenvolvimento local na sua config global e sobrescrever por projeto ou 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
• Chave de teste para suítes de teste de integração — acessa o sandbox, não produção
• 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.
• Use chaves de teste para testes automatizados. Isola atividade de teste dos dados de produção.
• 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

• Instalar CLI — Setup inicial de autenticação
• Schema de Configuração — Onde chaves são armazenadas e regras de precedência