API Keys

API keys allow you to access Fanfare’s API programmatically, enabling integrations with your own systems, automation, and custom workflows.

Accessing API Keys

API key management is available through the developer settings or integrations section. Caption: Manage your API keys for programmatic access

API Key Types

Type	Description	Use Case
Public Key	Client-side, limited permissions	Browser SDK, embedded widgets
Secret Key	Server-side, full permissions	Backend integrations, webhooks
Test Key	Testing environment only	Development and testing

Creating API Keys

Generate a New Key

Navigate to API Keys settings
Click Create API Key
Select the key type
Name the key (for identification)
Set permissions (if applicable)
Click Create

Caption: Create a new API key with appropriate permissions

Key Configuration

Field	Required	Description
Name	Yes	Descriptive name for the key
Type	Yes	Public, Secret, or Test
Permissions	No	Scope limitations (if supported)
Expiration	No	Optional expiration date

After Creation

When a key is created:

The key is displayed once
Copy and store it securely
You cannot view the full key again
The key appears in your key list

Secret keys are shown only once when created. Store them securely immediately. If lost, you must create a new key.

Managing Keys

Key List

View all your API keys:

Column	Description
Name	Key identifier
Type	Public, Secret, or Test
Created	When the key was generated
Last Used	Most recent API call
Status	Active, Inactive, or Expired

Key Actions

Action	Description
Regenerate	Create a new key, invalidate old
Deactivate	Temporarily disable the key
Delete	Permanently remove the key

Caption: Manage keys through the action menu

Key Permissions

Permission Scopes

If your plan supports granular permissions:

Scope	Description
read:experiences	View experience data
write:experiences	Create and edit experiences
read:consumers	View consumer data
write:consumers	Create and edit consumers
read:analytics	Access analytics data
admin	Full administrative access

Restricting Permissions

For enhanced security:

Select only needed permissions
Use separate keys for different purposes
Review permissions regularly
Revoke unnecessary access

Using API Keys

Authentication Methods

Method	Format
Header	`Authorization: Bearer <api_key>`

Example Request

curl -X GET "https://admin.fanfare.io/api/experiences" \
  -H "Authorization: Bearer $FANFARE_SECRET_KEY"

Server Usage

Use secret keys only from trusted server-side code. Browser and mobile integrations should use publishable keys through the SDK setup documented in the SDK section.

const response = await fetch("https://admin.fanfare.io/api/experiences", {
  headers: {
    Authorization: `Bearer ${process.env.FANFARE_SECRET_KEY}`,
  },
});

Key Security

Best Practices

Never expose secret keys - Keep server-side only
Use environment variables - Don’t hardcode keys
Rotate regularly - Replace keys periodically
Monitor usage - Watch for unusual activity
Limit permissions - Use minimal required scope

Environment Variables

Store keys securely:

# .env file (never commit to version control)
FANFARE_API_KEY=sk_live_xxxxx
FANFARE_PUBLIC_KEY=pk_live_xxxxx

Key Rotation

Schedule regular key rotation:

Scenario	Rotation Frequency
Production	Every 90 days
After breach	Immediately
Team member leaves	Immediately
Test environments	As needed

Rate Limits

API keys are subject to rate limits:

Plan	Rate Limit
Free	100 requests/minute
Basic	1,000 requests/minute
Pro	10,000 requests/minute
Enterprise	Custom limits

Rate Limit Headers

Responses include rate limit information:

Header	Description
`X-RateLimit-Limit`	Maximum requests allowed
`X-RateLimit-Remaining`	Requests remaining
`X-RateLimit-Reset`	When limit resets (timestamp)

Monitoring Usage

Usage Statistics

Track API key usage:

Metric	Description
Total Requests	Requests in current period
Success Rate	Percentage of successful calls
Error Rate	Percentage of failed calls
Last Used	Most recent API call

Usage Alerts

Configure alerts for:

Approaching rate limits
Unusual activity patterns
Error rate thresholds
Unused keys

Troubleshooting

Invalid API Key

Verify the key is correct
Check the key hasn’t expired
Ensure the key is active
Confirm correct environment (test vs. live)

Permission Denied

Check key has required permissions
Verify the endpoint requires no additional auth
Review permission scopes
Try regenerating the key

Rate Limited

Check current usage against limits
Implement exponential backoff
Cache responses where appropriate
Consider upgrading plan

API Documentation

For detailed API documentation:

API Reference - Complete endpoint documentation
Authentication Guide - Auth details
SDK Documentation - Client libraries

Settings Overview - All settings
Integrations - Third-party connections
Developer Documentation - API usage guides

Getting Started

Experiences

Audiences

Consumers

Loyalty

Settings

Analytics

Billing

Accessing API Keys

API Key Types

Creating API Keys

Generate a New Key

Key Configuration

After Creation

Managing Keys

Key List

Key Actions

Key Permissions

Permission Scopes

Restricting Permissions

Using API Keys

Authentication Methods

Example Request

Server Usage

Key Security

Best Practices

Environment Variables

Key Rotation

Rate Limits

Rate Limit Headers

Monitoring Usage

Usage Statistics

Usage Alerts

Troubleshooting

Invalid API Key

Permission Denied

Rate Limited

API Documentation

​Accessing API Keys

​API Key Types

​Creating API Keys

​Generate a New Key

​Key Configuration

​After Creation

​Managing Keys

​Key List

​Key Actions

​Key Permissions

​Permission Scopes

​Restricting Permissions

​Using API Keys

​Authentication Methods

​Example Request

​Server Usage

​Key Security

​Best Practices

​Environment Variables

​Key Rotation

​Rate Limits

​Rate Limit Headers

​Monitoring Usage

​Usage Statistics

​Usage Alerts

​Troubleshooting

​Invalid API Key

​Permission Denied

​Rate Limited

​API Documentation

​Related Guides

Accessing API Keys

API Key Types

Creating API Keys

Generate a New Key

Key Configuration

After Creation

Managing Keys

Key List

Key Actions

Key Permissions

Permission Scopes

Restricting Permissions

Using API Keys

Authentication Methods

Example Request

Server Usage

Key Security

Best Practices

Environment Variables

Key Rotation

Rate Limits

Rate Limit Headers

Monitoring Usage

Usage Statistics

Usage Alerts

Troubleshooting

Invalid API Key

Permission Denied

Rate Limited

API Documentation

Related Guides