Skip to content

API Authentication

FuncSpec uses API keys for all programmatic access. API keys are scoped to an organization and respect the permissions of the key owner.

Creating an API Key

  1. Go to Organization Settings → API Keys
  2. Click Create API Key
  3. Enter a descriptive name (e.g., "GitHub Actions", "Local dev")
  4. Click Create
  5. Copy the key immediately — it is only shown once

Warning

Store API keys securely. FuncSpec only shows the full key at creation time. After that, you can only see the key name and its last four characters.

Using an API Key

Pass the key in the X-Api-Key request header:

curl https://funcspec.net/api/v1/projects \
  -H "X-Api-Key: fs_live_abc123..."

All API endpoints require this header. Requests without a valid key return 401 Unauthorized.

Key Format

API keys are prefixed to indicate their type:

Prefix Type
fs_live_ Production key (funcspec.net)
fs_test_ Test key (where supported)

Managing Keys

Listing keys

In Organization Settings → API Keys, you can see:

  • Key name
  • Last four characters of the key
  • Created date
  • Last used date and IP address
  • Created by (which user generated it)

Revoking a key

Click Delete next to any key. Revocation is immediate — any in-flight requests using that key will fail.

Tip

When rotating keys, create the new key first, update all systems using it, then revoke the old key. This avoids downtime.

Multiple keys

Create separate keys for different use cases:

  • One key per CI/CD pipeline
  • Separate keys for local development vs. production integrations
  • Different keys for different team members who need programmatic access

This way you can revoke a single key if it's compromised without affecting other systems.

Rate Limits

Every API key is subject to rate limiting based on your plan. See Rate Limiting for details and current limits.

Rate limit headers are included in every response:

X-RateLimit-Limit: 10000
X-RateLimit-Remaining: 9847
X-RateLimit-Reset: 1743100800

Error Responses

401 Unauthorized — Missing key

curl https://funcspec.net/api/v1/projects
# No X-Api-Key header provided

{
  "error": {
    "code": "unauthorized",
    "message": "API key required. Pass your key in the X-Api-Key header."
  }
}

401 Unauthorized — Invalid key

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid API key."
  }
}

403 Forbidden — Insufficient permissions

{
  "error": {
    "code": "forbidden",
    "message": "You do not have permission to perform this action."
  }
}

This occurs when your API key is valid but the associated user lacks the required role for the requested project or operation.

429 Too Many Requests

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Try again after 2026-03-31T16:00:00Z"
  }
}

Security Best Practices

Environment variables: Never hardcode API keys in source code. Use environment variables or a secrets manager:

export FUNCSPEC_API_KEY="fs_live_abc123..."
curl -H "X-Api-Key: $FUNCSPEC_API_KEY" https://funcspec.net/api/v1/projects

CI/CD secrets: In GitHub Actions, add the key as a repository secret and reference it in your workflow:

- name: Review all specs
  run: funcspec ai review-all --project my-app
  env:
    FUNCSPEC_API_KEY: ${{ secrets.FUNCSPEC_API_KEY }}

Key rotation: Rotate keys periodically (quarterly is a reasonable default) and immediately when team members with access leave.

Minimal scope: The API key inherits the permissions of the user who created it. Create keys using accounts with the minimum necessary access level.

Next Steps