Access Control

FLXBL provides built-in role-based access control (RBAC) to secure your data. Define roles with specific permissions, then assign users and API keys to those roles.

How It Works

Every API request is authorized based on the caller's role and permissions. FLXBL checks permissions automatically before executing any operation.

flowchart LR
    subgraph request [API Request]
        A[Client] -->|Bearer Token| B[FLXBL API]
    end
    
    subgraph auth [Authorization]
        B --> C{Check Token}
        C -->|Valid| D[Extract Role]
        C -->|Invalid| E[401 Unauthorized]
        D --> F{Check Permission}
        F -->|Granted| G[Execute Operation]
        F -->|Denied| H[403 Forbidden]
    end
    
    G --> I[Response]

Two Levels of Access Control

FLXBL provides access control for your tenant operations. For your application's end-users, you implement your own authorization logic.

flowchart LR
    subgraph flxbl [FLXBL Manages]
        TenantRBAC["Tenant RBAC"]
        Roles["Roles & Permissions"]
        APIScopes["API Key Scopes"]
    end
    
    subgraph yourApp [You Implement]
        AppRBAC["Application RBAC"]
        UserRoles["Role field on entity"]
        Middleware["Your auth middleware"]
    end
    
    TenantRBAC --- Roles
    TenantRBAC --- APIScopes
    
    AppRBAC --- UserRoles
    AppRBAC --- Middleware

For end-users, add a role field to your identity entity and enforce permissions in your application code. Learn more in Integration Patterns.

Permissions

Permissions are automatically generated based on your schema. When you publish a schema with entities and relationships, FLXBL creates corresponding permissions.

Permission Format

// Permission format
entity:{EntityName}:{operation}
relationship:{RelationshipName}:{operation}

// Operations
create = create new records
read = read/query records  
update = modify existing records
delete = remove records
* = all operations

For example, with a schema containing Product and Category entities:

Roles

Roles are named collections of permissions. Create roles that match your organization's access patterns, then assign users to roles.

flowchart TB
    subgraph roles [Role Hierarchy]
        Admin["Admin (Full access)"]
        Editor["Editor (Create, Read, Update)"]
        Viewer["Viewer (Read only)"]
    end
    
    Admin --> Editor
    Editor --> Viewer

Built-in Roles

FLXBL provides default roles to get you started:

Creating Custom Roles

Create roles tailored to your application's needs:

// Example: Creating a "Content Manager" role

// Via API
POST /api/v1/roles
{
  "name": "Content Manager",
  "permissions": [
    "entity:Article:*",              // Full access to Articles
    "entity:Category:read",          // Read-only Categories
    "relationship:AUTHORED_BY:*"     // Manage authorship
  ]
}

// Via MCP
"Create a role called Content Manager with full 
 Article access and read-only Category access"

Assigning Roles to Users

// Assign role to a user
PATCH /api/v1/users/:userId/role
{
  "roleId": "role_content_manager_abc123"
}

Permission Checks

FLXBL automatically enforces permissions on every API call. You can also explicitly check permissions in your application:

// Check if current user has permission
GET /api/v1/auth/check-permission?permission=entity:Article:create

// Response
{
  "hasPermission": true,
  "role": "Content Manager"
}

API Key Scopes

API keys can be scoped to a subset of the creating user's permissions. This follows the principle of least privilege - give each integration only the access it needs.

// API keys inherit role permissions
// But can be further restricted with scopes

POST /api/v1/api-keys
{
  "name": "blog-frontend",
  "scopes": [
    "entity:Article:read",   // Only read Articles
    "entity:Author:read"     // Only read Authors
  ]
}

// This key cannot create/update/delete even if 
// the creating user has those permissions

Learn more about creating and managing API keys in the API Keys documentation.

Best Practices

Principle of Least Privilege

• Grant only the permissions each role actually needs
• Use read-only roles for dashboards and reporting
• Scope API keys to specific operations

Role Design

• Create roles that match real job functions
• Avoid creating too many granular roles
• Document what each role is intended for

API Key Management

• Create separate API keys for each integration
• Rotate keys periodically
• Revoke keys immediately when no longer needed
• Never expose API keys in client-side code

Next Steps

• API Keys - Create and manage scoped API keys
• User Management - Invite team members and manage access
• Identity Configuration - Configure authentication settings