API Keys

Overview

API keys let you authenticate requests to the Firstrun Content Sync API. Each key is scoped to your organization and grants full access to sync endpoints. You need at least one active API key before you can push content via the API, CLI, or GitHub Action.

Requirements: API keys are available on the Pro and Enterprise plans. Only organization owners and admins can create and manage keys.

Creating an API Key

1. Open Settings from the sidebar.
2. Go to the API Keys tab.
3. Enter a descriptive name for the key (e.g. “CI pipeline”).
4. Click Create API Key.
5. Copy the key immediately — it will not be shown again.

Security

Your API key is displayed only once at creation time. After that, Firstrun stores a SHA-256 hash of the key — the raw value cannot be retrieved. If you lose the key, revoke it and create a new one.

• Never commit API keys to version control.
• Store keys in environment variables or a secrets manager (e.g. GitHub Actions secrets).
• Rotate keys periodically and revoke any that are no longer in use.

Using Your Key

Include your API key in the Authorization header as a Bearer token:

curl -X POST https://api.firstrun.dev/v1/sync \
  -H "Authorization: Bearer fr_key_a1b2c3d4e5f6..." \
  -H "Content-Type: application/json" \
  -d '{"wizard_id": "wiz_abc123", "steps": [...]}'

Key Limits

Each organization can have up to 5 active API keys at a time. If you need more, revoke unused keys first.

Revoking a Key

1. Open Settings → API Keys.
2. Click the Revoke button next to the key you want to remove.
3. Confirm the action.

Revocation takes effect immediately. Any integrations using that key will start receiving 401 Unauthorized responses. Make sure to update your CI/CD pipelines before revoking a key that is still in use.

Key Format

All API keys use the following format:

fr_key_<32 hex characters>

The fr_key_ prefix makes it easy to identify Firstrun keys in your configuration and enables secret scanning tools to flag accidental exposure.