Getting Started

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/workspaces/{workspace_id}/people',
  {
    method: 'GET',
    headers: {
      'Authorization': 'Bearer ws_live_abc12345_abc123.your_secret_here'
    }
  }
);

import requests

response = requests.get(
    'https://api.flameup.ai/api/v1/workspaces/{workspace_id}/people',
    headers={
        'Authorization': 'Bearer ws_live_abc12345_abc123.your_secret_here'
    }
)

API Key Environments

Flameup provides two environments for your API keys:

Live Keys

Prefix: ws_live_...

Use for production applications. Events and data are stored permanently.

Test Keys

Prefix: ws_test_...

Use for development and testing. Safe for experimentation.

Test and live environments are completely isolated. Data created with test keys won't appear in your live environment.

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:write`	Register push notification tokens
Admin	`admin`, `*`	Full 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")
Environment: Live or Test
Permissions: Select the required permissions
Expiration (optional): Set an expiry date
IP Whitelist (optional): Restrict to specific IPs

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

IP Whitelisting

Restrict API key usage to specific IP addresses or CIDR ranges:

{
  "ip_whitelist": [
    "192.168.1.100",
    "10.0.0.0/8",
    "2001:db8::/32"
  ]
}

Key Expiration

Set an expiration date for API keys that should only be valid for a limited time:

{
  "expires_at": "2025-12-31T23:59:59Z"
}

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": {
    "code": "unauthorized",
    "message": "Invalid or missing API key"
  }
}

403 Forbidden

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

{
  "error": {
    "code": "forbidden",
    "message": "API key lacks required permission: people:write"
  }
}

429 Too Many Requests

Returned when rate limits are exceeded:

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Retry after 60 seconds.",
    "retry_after": 60
  }
}

Best Practices

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

Was this page helpful?

Built with Documentation.AI

Last updated today