API Keys

API keys authenticate external systems when they interact with FanFest's APIs. They are scoped to a single channel and used for features like event tracking from your backend, loyalty system integration, and external action ingestion.

Accessing API Key Management

1. Navigate to your channel
2. Click the Settings gear icon
3. Select API Keys from the dropdown

Creating an API Key

1. Click Generate New Key (or Generate Your First Key if no keys exist yet)
2. In the modal that appears:
   • Enter a Name (required) -- a descriptive label like "Production Backend" or "Staging Event Tracker"
   • Enter a Description (optional) -- additional context about what the key is used for
3. Click Create

Saving Your Key

After creation, the API key token is displayed once. This is the only time you will see the full key.

Important

Copy or download your API key immediately after creation. FanFest stores only a fingerprint (hash) of the key for identification -- the actual key cannot be retrieved later.

You have two options to save the key:

• Copy -- Click the copy button to copy the key to your clipboard
• Download -- Click the download button to save the key as a .txt file

Managing API Keys

The API key table displays all keys for your channel with the following information:

Column	Description
Name	The key's name, description, and fingerprint
Created	When the key was created
Last Used	When the key was last used for an API request (or "Never used" if unused)
Status	Current status: Active or Revoked
Usage	Total number of API requests made with this key
Actions	Revoke or delete the key

Key Properties

Each API key has these properties:

• Name -- Descriptive label you provide during creation
• Description -- Optional additional context
• Key Fingerprint -- A hash of the API key, displayed as a monospace string for identification
• Channel Scope -- API keys are bound to the channel where they were created
• Created By -- The user who generated the key
• Expiration -- Optional expiration date (keys without an expiration remain valid until revoked)
• Permissions -- Scoped permissions for future extensibility (e.g., loyalty:read for egress API access)

Usage Tracking

FanFest tracks every API request made with each key, recording:

• The endpoint accessed
• HTTP method used
• Whether the key was accepted
• Response status code
• Response time

This data is reflected in the Usage count column and helps you audit key activity.

Revoking a Key

Revoking a key immediately disables it without deleting the record. This is useful when you suspect a key may be compromised or when you want to disable access temporarily.

1. Find the key in the table
2. Click the Revoke button (only shown for active keys)
3. Confirm the revocation in the dialog

Revoked keys show a "Revoked" status badge and can no longer authenticate API requests. The key record and its usage history are preserved.

Deleting a Key

Deleting permanently removes the key and all its associated usage history.

1. Find the key in the table
2. Click the Delete button
3. Confirm the deletion in the dialog

WARNING

Deletion is permanent. If you only need to disable a key temporarily, use Revoke instead.

Key Rotation Best Practices

• Rotate keys periodically -- Create a new key, update your integrations, then revoke the old key.
• Use descriptive names -- Include the environment (production, staging) and purpose in the name so you can identify keys at a glance.
• One key per integration -- Create separate keys for different systems or environments. This makes it easy to revoke access for a single integration without affecting others.
• Monitor usage -- Check the "Last Used" and "Usage" columns regularly. Keys that have not been used in a long time may be candidates for revocation.
• Never commit keys to source control -- Store API keys in environment variables or secret management systems, never in code repositories.

Using API Keys

API keys are sent in the x-api-key HTTP header when making requests to FanFest's external APIs:

curl -H "x-api-key: YOUR_API_KEY" \
  https://api.fanfest.vip/public/external-actions/ingest

See the Integration Guide for details on which API endpoints accept API key authentication.