Authentication

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.

API Key Format

Flameup API keys follow this format:

{prefix}.{secret}

Where:

• Prefix: {type}_{env}_{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. Only the prefix is stored in readable form — the secret is stored as a hash, which is why a key cannot be retrieved after creation.

Two kinds of key

The prefix tells you where a key is allowed to live.

These are the only two prefixes. The environment label on a key (live or test) does not change them — a test-labelled key is still minted with a ws_live_ or pk_live_ prefix.

A public key is restricted by the server, not by convention: a permission outside that list is rejected when the key is created and when it is updated, so one cannot be widened later.

Authentication Methods

Authorization Header

Pass your API key in the Authorization header using the Bearer scheme. This is the only method — there is no query-parameter or cookie alternative:

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

import requests

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

curl -X GET "https://api.flameup.ai/api/v1/people" \
  -H "Authorization: Bearer ws_live_abc12345_abc123.your_secret_here"

What an API key can reach

An API key reaches the ingestion and messaging surfaces. Everything else in Flameup is built in the dashboard and authenticated with your dashboard session, not a key.

With an API key:

Dashboard only — an API key will not work: workflows, segments, message templates, schedules, campaign create/edit/delete, messaging channel setup, team and workspace management.

Permissions

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

Permission Categories

These twelve strings are the complete set any route checks:

Thirteen other permission names (events:list, people:list, campaigns:read, campaigns:write, analytics:read, analytics:write, segments:read, segments:write, webhooks:read, webhooks:write, workspace:read, workspace:write, admin) are accepted when a key is created but gate no route — a key holding only them can reach nothing. Do not grant them expecting access. admin is the one to watch: despite the name it grants nothing at all, and it is not a synonym for *.

people:identify deserves its own note. It authorizes POST /identify and nothing else — creating or updating one person's traits by an identifier you already know. It is deliberately narrower than people:write, which also carries /people CRUD and a 1000-operation batch route, and it is the only people: permission a public key may hold.

Common Permission Sets

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

{
  "permissions": [
    "events:write",
    "people:write"
  ]
}

{
  "permissions": ["*"]
}

{
  "permissions": [
    "events:read",
    "events:write",
    "people:read",
    "people:write",
    "people:identify",
    "people:delete",
    "devices:read",
    "devices:write",
    "devices:register",
    "campaigns:trigger",
    "push:send",
    "push:read"
  ]
}

Creating API Keys

Creating API Keys via the API

Key creation is authenticated with a dashboard session token, not with an API key — a key cannot mint another key. Use this when provisioning programmatically.

Endpoint: POST /api/v1/workspaces/{workspace_id}/api-keys

curl -X POST "https://api.flameup.ai/api/v1/workspaces/{workspace_id}/api-keys" \
  -H "Authorization: Bearer {dashboard_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Backend Server",
    "permissions": ["events:write", "people:write", "people:read"],
    "environment": "live"
  }'

curl -X POST "https://api.flameup.ai/api/v1/workspaces/{workspace_id}/api-keys" \
  -H "Authorization: Bearer {dashboard_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Android app",
    "key_type": "public",
    "permissions": ["events:write", "devices:register", "people:identify"],
    "environment": "live"
  }'

Response (201):

{
  "success": true,
  "api_key": {
    "id": "8f2a...",
    "key_prefix": "pk_live_abc12345_abc123",
    "key": "pk_live_abc12345_abc123.a1b2c3...",
    "permissions": ["events:write", "devices:register", "people:identify"],
    "key_type": "public"
  },
  "warning": "This is the only time the full API key will be shown. Please save it securely."
}

key is the value you authenticate with. It appears here and in a refresh response — nowhere else. key_prefix is safe to log and to display later.

Managing Keys

The same dashboard-token surface carries the full key lifecycle:

PUT updates only the fields present in the body: name, description, permissions, environment, expires_at, ip_whitelist. Permissions are revalidated against the key's stored type, so a public key cannot be widened after the fact. expires_at is three-state: omit it to leave the expiry unchanged, send a timestamp to set it, or send an explicit null to clear it and make the key non-expiring.

Security Features

Key Rotation

Regularly rotate your API keys for security. The refresh endpoint mints a new secret for the same key: the key_prefix, id, and permissions are unchanged, and the response carries the new full key — the only time it is shown. The old secret stops working immediately.

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.",
  "scope": "ws-ingest",
  "gate": "local"
}

See Rate Limits for what scope and gate mean.

Best Practices