API Keys

API keys provide secure, scoped access to your FLXBL backend. Create keys for your applications, integrations, and services with exactly the permissions they need.

How API Keys Work

API keys are tokens that authenticate requests to the FLXBL API. Each key is scoped to specific permissions, following the principle of least privilege.

100% Drag to pan 
flowchart LR
    subgraph creation [Key Creation]
        A[Dashboard/MCP] --> B[Define Scopes]
        B --> C[Generate Key]
        C --> D[flxbl_xxxxx]
    end
    
    subgraph usage [Key Usage]
        D --> E[Authorization Header]
        E --> F[API Request]
        F --> G{Scope Check}
        G -->|Allowed| H[Success]
        G -->|Denied| I[403 Forbidden]
    end
API key creation and usage flow

Key Concepts

Scoped Permissions

Unlike traditional API keys that grant full access, FLXBL keys are scoped. When you create a key, you specify exactly which operations it can perform.

100% Drag to pan 
flowchart TB
    subgraph user [User Permissions]
        UP[Full Admin Access]
    end
    
    subgraph key1 [API Key: Frontend]
        K1["Product:read, Category:read"]
    end
    
    subgraph key2 [API Key: Backend]
        K2["Order:*, Product:read"]
    end
    
    subgraph key3 [API Key: Analytics]
        K3[entity:*:read]
    end
    
    UP --> K1
    UP --> K2
    UP --> K3
One user can create multiple keys with different scopes

Scope Format

// Scope patterns

// Single entity, single operation
entity:Product:read       // Read products
entity:Order:create       // Create orders
entity:Product:update     // Update products  
entity:Product:delete     // Delete products

// Single entity, all operations
entity:Product:*          // Full access to products

// All entities, single operation
entity:*:read             // Read all entities

// All entities, all operations
entity:*:*                // Full access (admin)

// Relationship scopes
relationship:BELONGS_TO:read  // Read relationships
relationship:*:*              // All relationship operations

Creating API Keys

Via REST API

// Create a scoped API key via REST API
POST /api/v1/api-keys
{
  "name": "mobile-app-readonly",
  "scopes": [
    "entity:Product:read",
    "entity:Category:read",
    "entity:Review:read"
  ]
}

// Response
{
  "id": "key_abc123def456",
  "name": "mobile-app-readonly",
  "key": "flxbl_ab12cd34_7f8g9h...",  // Only shown once!
  "scopes": ["entity:Product:read", "entity:Category:read", "entity:Review:read"],
  "createdAt": "2025-01-15T10:30:00Z"
}
Important: The key value is only shown once at creation time. Store it securely - you cannot retrieve it later.

Via MCP (AI Assistant)

// Using the FLXBL MCP tool
// In Cursor/Windsurf, ask the AI:

"Create an API key called 'mobile-app' with 
 read-only access to Products and Categories"

// The AI will use manage_access_keys with:
{
  "action": "create",
  "name": "mobile-app",
  "scopes": [
    "entity:Product:read",
    "entity:Category:read"
  ]
}

Via Dashboard

  1. Log in to your FLXBL dashboard at platform.flxbl.dev
  2. Navigate to Settings → API Keys
  3. Click Create New Key
  4. Enter a descriptive name
  5. Select the scopes for this key
  6. Click Generate
  7. Copy and securely store the key

Using API Keys

Include your API key in the Authorization header:

// Using an API key for authentication
curl -X GET https://api.flxbl.dev/api/v1/dynamic/Product \
  -H "Authorization: Bearer flxbl_ab12cd34_7f8g9h..."

// JavaScript/TypeScript
const response = await fetch('https://api.flxbl.dev/api/v1/dynamic/Product', {
  headers: {
    'Authorization': 'Bearer flxbl_ab12cd34_7f8g9h...'
  }
});

// Python
import requests

response = requests.get(
    'https://api.flxbl.dev/api/v1/dynamic/Product',
    headers={'Authorization': 'Bearer flxbl_ab12cd34_7f8g9h...'}
)

Managing Keys

List All Keys

// List all API keys
GET /api/v1/api-keys

// Response
{
  "keys": [
    {
      "id": "key_abc123",
      "name": "mobile-app-readonly",
      "scopes": ["entity:Product:read"],
      "createdAt": "2025-01-15T10:30:00Z",
      "lastUsed": "2025-01-16T14:22:00Z"
    },
    {
      "id": "key_def456",
      "name": "backend-service",
      "scopes": ["entity:Order:*"],
      "createdAt": "2025-01-10T08:00:00Z",
      "lastUsed": "2025-01-16T15:45:00Z"
    }
  ]
}

Revoking Keys

Immediately revoke a key when it's no longer needed or if you suspect it has been compromised: 

// Revoke an API key
DELETE /api/v1/api-keys/key_abc123

// Via MCP
"Delete the API key called 'mobile-app-readonly'"

Use Cases

Frontend Application

Create a read-only key for your frontend to fetch public data. Never expose write permissions to client-side code.

Key Name Scopes Purpose
website-public entity:Product:read, entity:Category:read Display product catalog

Backend Service

Create keys for your backend services with the specific permissions they need:

Key Name Scopes Purpose
order-service entity:Order:*, entity:Product:read Process orders
inventory-sync entity:Product:update Update stock levels
analytics-reader entity:*:read Read-only for reporting

Third-Party Integrations

When connecting external services, create dedicated keys with minimal scope:

Key Name Scopes Purpose
zapier-webhook entity:Contact:create Create contacts from form submissions
analytics-export entity:Event:read Export events to analytics platform

Security Best Practices

Key Storage

  • Never commit keys to version control - Use environment variables
  • Store keys in secret management systems (AWS Secrets Manager, HashiCorp Vault, etc.)
  • Limit who can access production keys

Key Hygiene

  • One key per integration - Makes revocation easy
  • Rotate keys periodically - Even if not compromised
  • Revoke unused keys - Reduce attack surface
  • Monitor usage - Check lastUsed for anomalies

Scope Minimization

  • Grant only the permissions each integration needs
  • Use read-only scopes for analytics and reporting
  • Never give frontend keys write access

Troubleshooting

"Invalid API key"

  • Verify the key is correct and complete
  • Check if the key was revoked
  • Ensure you're using the right key for the environment (staging vs production)

"Forbidden - insufficient permissions"

  • The key doesn't have the required scope for this operation
  • Check the key's scopes and add the necessary permission
  • Or create a new key with broader scope

Next Steps