Authentication

Flapjack supports two authentication methods: API keys for programmatic/SDK access, and Supabase JWT for dashboard and direct API access.

API Keys (SDK / Programmatic Access)

API keys are the primary authentication method for the SDK and programmatic access.

Format

fj_live_<random_hex>

All Flapjack API keys start with the fj_live_ prefix.

Creating a Key

1. Go to flapjack.chat → Keys
2. Click Create Key
3. Copy the key immediately — it is shown only once

The raw key is never stored. Flapjack stores a SHA-256 HMAC hash of the key for verification.

Using a Key

Pass the key as a Bearer token in the Authorization header:

curl https://api.flapjack.dev/api/agents \
  -H "Authorization: Bearer fj_live_..."

const client = new FlapjackClient({
  apiKey: 'fj_live_...',
});

📋 Copy as prompt

Set up a FlapjackClient with my API key from the FLAPJACK_API_KEY environment variable.

Key Properties

Property	Description
id	Unique identifier
prefix	First 12 characters + ... (for display)
name	Optional label
last_used_at	Last time the key was used
created_at	When the key was created

Revoking a Key

Key management endpoints require user authentication (Supabase JWT). API keys (fj_live_*) are rejected.

curl -X DELETE https://api.flapjack.dev/api/keys/{keyId} \
  -H "Authorization: Bearer <supabase-jwt>"

Demo API Key (Try Without Signing Up)

Flapjack provides a public demo key for quick SDK evaluation without creating an account.

Format

fj_demo_example_key

All demo keys use the fj_demo_ prefix.

Usage

Pass it exactly like a regular API key:

const client = new FlapjackClient({
  apiKey: 'fj_demo_example_key',
});

Limitations

Constraint	Detail
Mock data only	All responses are canned fixtures — no real agents, threads, or data are created.
Stubbed writes	Thread creation (POST), thread update (PATCH), and message sending (POST) return mock responses (a demo thread or a canned SSE stream). Other write operations return DEMO_KEY_READ_ONLY (403).
Rate-limited	Per-IP rate limiting to prevent abuse.
Restricted surface	Only works on demo-eligible endpoints: /api/threads, /api/agents, /api/knowledge, /api/keys, and /api/orgs/settings. Internal, cron, and webhook routes are blocked.

The demo SSE stream points users to flapjack.chat to sign up and generate a real fj_live_* key.

Supabase JWT (Dashboard Access)

The Flapjack dashboard uses Supabase authentication. When making direct API calls (not through the SDK), you can use a Supabase JWT:

Authorization: Bearer <supabase-jwt>

This is primarily used by the dashboard frontend. For programmatic access, use API keys instead.

Security Best Practices

Never expose API keys client-side

API keys should only be used server-side. In browser applications, use a server-side proxy:

// ❌ Bad: API key in client-side code
const client = new FlapjackClient({
  apiKey: 'fj_live_...',  // Visible in browser DevTools!
});

// ✅ Good: Server-side proxy
// See: SDK > Server Proxy pattern

→ Server Proxy Pattern

Environment variables

# .env.local (server-side)
FLAPJACK_API_KEY=fj_live_...

# Never use NEXT_PUBLIC_ prefix for API keys in production

Key rotation

• Create a new key before revoking the old one
• Update your environment variables
• Revoke the old key

Organization Scoping

API keys are scoped to an organization. All resources accessed through a key belong to the key's organization. A key cannot access resources in other organizations.

Next Steps

• API: Keys — key management endpoints
• SDK: Server Proxy — secure production pattern
• API: Overview — error handling and base URLs