Authentication

Learn how to authenticate your API requests with Flameup

Authentication Overview

Flameup uses API keys to authenticate requests. Each API key is scoped to a specific workspace and has granular permissions that control what operations it can perform.

Keep your API keys secure. Never expose them in client-side code, public repositories, or logs. If a key is compromised, revoke it immediately from your dashboard.

API Key Format

Flameup API keys follow this format:

{prefix}.{secret}

Where:

Prefix: ws_live_{workspace_short}_{random} (e.g., ws_live_abc12345_abc123)
Secret: 64 hexadecimal characters

Full example:

ws_live_abc12345_abc123.a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2

The prefix includes a shortened workspace ID for identification.

Authentication Methods

Authorization Header (Recommended)

Pass your API key in the Authorization header using the Bearer scheme:

const response = await fetch(
  'https://api.flameup.ai/api/v1/people',
  {
    method: 'GET',
    headers: {
      'Authorization': 'Bearer ws_live_abc12345_abc123.your_secret_here'
    }
  }
);

Permissions

API keys have granular permissions that control access to different resources:

Permission Categories

Category	Permissions	Description
Events	`events:read`, `events:write`, `events:list`	Read and track user events
People	`people:read`, `people:write`, `people:delete`, `people:list`	Manage user profiles
Campaigns	`campaigns:read`, `campaigns:write`, `campaigns:trigger`	Manage and trigger campaigns
Analytics	`analytics:read`	Access reporting data
Workspace	`workspace:read`, `workspace:write`	Workspace settings
Devices	`devices:*`	Register push tokens — no granular scope yet; requires a `devices:` wildcard or a full-access `` key
Full Access	`*`	Wildcard granting access to all resources

Common Permission Sets

For dashboards and analytics that only need to view data:

{
  "permissions": [
    "events:read",
    "people:read",
    "campaigns:read",
    "analytics:read"
  ]
}

For backend services that need complete control:

{
  "permissions": ["*"]
}

Or explicitly:

{
  "permissions": [
    "events:read",
    "events:write",
    "people:read",
    "people:write",
    "people:delete",
    "campaigns:read",
    "campaigns:write",
    "campaigns:trigger"
  ]
}

Creating API Keys

Open Dashboard

Create New Key

Click "Create API Key" and provide:

Name: A descriptive name (e.g., "Backend Server", "Mobile App")
Permissions: Select the required permissions

Copy Your Key

Copy the full API key immediately. For security, the full key is only shown once.

The full API key is only displayed once when created. Store it securely - you cannot retrieve it later.

Security Features

Key Rotation

Regularly rotate your API keys for security. Use the refresh endpoint to generate a new key while maintaining the same permissions:

curl -X POST "https://api.flameup.ai/api/v1/workspaces/{workspace_id}/api-keys/{key_id}/refresh" \
  -H "Authorization: Bearer {dashboard_token}"

Error Responses

401 Unauthorized

Returned when no API key is provided or the key is invalid:

{
  "error": "Unauthorized",
  "message": "Invalid or expired API key",
  "details": "Please provide a valid API key in the Authorization header: Bearer <your_api_key>"
}

403 Forbidden

Returned when the API key doesn't have the required permissions:

{
  "error": "Forbidden",
  "message": "Insufficient permissions"
}

429 Too Many Requests

Returned when rate limits are exceeded:

{
  "error": "Rate limit exceeded",
  "message": "Too many requests. Please try again later."
}

Best Practices

Create separate API keys for development, staging, and production. Never use production keys in development environments.

Was this page helpful?