Skip to Content
ConfigurationAPI Keys

API Keys

Create, manage, and secure API keys for authenticating with SpecForge.

API keys authenticate the CLI, the MCP server, and any direct API calls to your SpecForge project. Every request to SpecForge must include a valid key.

Creating an API Key

  1. Open your project in the SpecForge dashboard
  2. Navigate to Settings > API Keys
  3. Click Generate New Key
  4. Give the key a descriptive label (e.g., “Local Development”, “CI Pipeline”)
  5. Copy the key immediately

⚠️ API keys are shown only once at creation. If you lose a key, revoke it and generate a new one.

Key Format

Every SpecForge key carries the sf_live_ prefix:

PrefixPurpose
sf_live_Full access to your project’s data and specifications

sf_live_ is the only key format SpecForge issues, and the only one the API accepts — any token without this prefix is rejected at authentication.

Using Your API Key

specforge login

Opens a browser-based authentication flow and stores credentials in ~/.specforge/config.json automatically. Simplest for day-to-day development.

Option 2: API Key Flag (headless environments)

specforge login --api-key sf_live_...

Use for remote servers, CI pipelines, or any environment without a browser.

Option 3: Environment Variable (CI/CD)

export SPECFORGE_API_KEY="sf_live_..."

The recommended approach for CI/CD pipelines and containerized environments. Store as a secret in your CI provider (GitHub Actions secrets, GitLab CI variables, etc.).

Precedence

The API key resolves from exactly two sources, most specific first:

  1. Environment variable SPECFORGE_API_KEY (highest)
  2. Global config ~/.specforge/config.json (lowest)

There is no project-level key tier: the key is never read from a project’s .specforge/config.json. This means you can keep a default key for local development in your global config and override it per-pipeline with an environment variable.

Managing Keys

Rotation

To rotate a key without downtime:

  1. Generate a new key in Settings > API Keys
  2. Update your CLI config or environment variable with the new key
  3. Verify connectivity with specforge doctor
  4. Revoke the old key from the dashboard

The gap between steps 1 and 4 is your rotation window. Both keys work simultaneously until the old one is revoked.

Revocation

Click Revoke next to any key in Settings > API Keys. Revocation is immediate — any request using that key fails with an authentication error from that moment.

Multiple Keys

Create as many keys as you need per project. Common patterns:

  • One key per developer for local development — if someone leaves, revoke their key without affecting others
  • Dedicated CI key for pipelines — isolated from dev keys, easy to rotate
  • Separate keys per deploy environment — staging and production use different keys

Security Practices

  • Never commit API keys to version control. Add ~/.specforge/config.json to your global gitignore or use environment variables exclusively.
  • Rotate keys periodically. If a key may have been exposed, revoke it immediately and generate a replacement.
  • Scope keys to their purpose. Separate keys for CI, local dev, and production makes it easy to revoke a compromised key without disrupting other workflows.
  • Use environment variables in CI. Store keys as secrets in your CI provider, never in config files that get committed.

✅ Run specforge doctor after any key change to verify authentication is working correctly.

See Also

Quality StandardsTeam Management