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

Open your project in the SpecForge dashboard
Navigate to Settings > API Keys
Click Generate New Key
Give the key a descriptive label (e.g., “Local Development”, “CI Pipeline”)
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

SpecForge uses prefixed keys so you can identify the environment at a glance:

Prefix	Environment	Purpose
`sf_live_`	Production	Full access to your project’s data and specifications
`sf_test_`	Test	Isolated sandbox for integration tests and CI

Test keys operate against an isolated copy of your project. Changes made with a test key don’t affect production data.

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

When multiple sources provide an API key, the most specific wins:

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

This means you can have a default key for local development in your global config and override it per-project or per-pipeline with an environment variable.

Managing Keys

Rotation

To rotate a key without downtime:

Generate a new key in Settings > API Keys
Update your CLI config or environment variable with the new key
Verify connectivity with specforge doctor
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
Test key for integration test suites — hits the sandbox, not production
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.
Use test keys for automated tests. Isolates test activity from production data.
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.