Overview

Feature flags provide kill-switch and gradual rollout capabilities. Flags can be targeted to specific segments, companies, or users.

Base URL

/api/admin/config/features

NOTE

These endpoints require authentication with a Super Admin account.

---

Endpoints

List Feature Flags

GET /api/admin/config/features

Returns all feature flags with their associated segments.

Response 200 OK

[
  {
    "id": "feedback_widget",
    "name": "Feedback Widget",
    "description": "Show feedback widget in app",
    "type": "boolean",
    "isEnabled": true,
    "status": "development",
    "companyOverrides": [],
    "userOverrides": ["marc.montecalvo@gmail.com"],
    "segments": [
      {
        "id": "ffs-123",
        "segmentId": "seg-456",
        "segment": {
          "id": "seg-456",
          "name": "beta-testers"
        }
      }
    ],
    "createdAt": "2025-12-01T00:00:00.000Z",
    "updatedAt": "2025-12-10T00:00:00.000Z"
  }
]

---

Create Feature Flag

POST /api/admin/config/features

Request Body

{
  "id": "new_dashboard_v2",
  "name": "New Dashboard V2",
  "description": "Redesigned dashboard layout",
  "isEnabled": false,
  "type": "boolean",
  "status": "development"
}

Field	Type	Required	Default	Description
id	string	✅	-	Code-defined ID (snake_case recommended)
name	string	✅	-	Human-readable name
description	string	❌	-	Feature description
isEnabled	boolean	❌	false	Global kill switch
type	string	❌	"boolean"	Flag type
status	string	❌	"development"	development, active, deprecated

Response 200 OK - Created flag object

---

Update Feature Flag

PUT /api/admin/config/features/:id

Parameters

Name	Type	Description
id	string	Feature flag ID

Request Body - All fields optional

{
  "isEnabled": true,
  "description": "Updated description",
  "status": "active",
  "companyOverrides": ["company-123"],
  "userOverrides": ["user@example.com"]
}

Field	Type	Description
isEnabled	boolean	Global kill switch
description	string	Feature description
status	string	Status: development, active, deprecated
companyOverrides	string[]	Company IDs that always have access
userOverrides	string[]	User IDs or emails that always have access

Response 200 OK - Updated flag object

---

Attach Segment to Flag

POST /api/admin/config/features/:id/segments

Parameters

Name	Type	Description
id	string	Feature flag ID

Request Body

{
  "segmentId": "seg-456"
}

Response 200 OK

{
  "id": "ffs-789",
  "featureFlagId": "feedback_widget",
  "segmentId": "seg-456"
}

---

Detach Segment from Flag

DELETE /api/admin/config/features/:id/segments/:segmentId

Parameters

Name	Type	Description
id	string	Feature flag ID
segmentId	string	Segment ID to detach

Response 200 OK

{
  "success": true
}

---

Access Evaluation Logic

When checking feature access, the system evaluates in this order:

1. Direct Overrides - If user/company is in overrides array → ALLOW
2. Segment Membership - If user/company is in any attached active segment → ALLOW
3. Global Switch - If isEnabled is true → ALLOW
4. Otherwise → DENY

import { isFeatureEnabled } from '../services/featureFlags.service.js';

const hasAccess = await isFeatureEnabled('my_feature', {
  companyId: 'company-123',
  userId: 'user-456',
  email: 'user@example.com'
});

---

See Also

• Platform Console Overview
• Segments API
• Entitlements API