Feature Flags

Feature flags are boolean switches that gate access to specific platform capabilities. Each tier has a predefined set of feature flags that control what the deployment can do.

Available Feature Flags

Flag	Type	Description	Tiers Enabled
`ai_enabled`	`boolean`	Access to AI completion and embedding proxy	Trial, Launch, Growth, Enterprise
`billing_enabled`	`boolean`	Access to Stripe billing proxy (checkout, portal)	Trial, Launch, Growth, Enterprise
`custom_domain`	`boolean`	Use a custom domain for the deployment	Launch, Growth, Enterprise
`white_label`	`boolean`	Remove HiveForge branding from the deployment	Growth, Enterprise
`mcp_enabled`	`boolean`	Access to MCP tool metering endpoints	Trial, Launch, Growth, Enterprise

Checking Feature Flags

Via the SDK

The HiveForge SDK provides direct access to feature flags through the entitlements module:

import { HiveForgeClient } from "@producthacker/hiveforge-sdk";
 
const client = new HiveForgeClient();
 
// Check a specific feature
const entitlements = await client.entitlements.check();
 
if (entitlements.features.ai_enabled) {
  // AI features are available
  const completion = await client.ai.complete({
    messages: [{ role: "user", content: "Hello" }],
  });
}
 
if (entitlements.features.custom_domain) {
  // Custom domain configuration is available
}

Via the API

Query the entitlement endpoint directly:

curl -X POST https://api.hiveforge.dev/api/v1/entitlements/check \
  -H "Content-Type: application/json" \
  -d '{
    "deployment_id": "d9f2a1b4-7c3e-4f8a-b5d6-1e2f3a4b5c6d",
    "deployment_secret": "sk_live_..."
  }'

Response shape:

{
  "status": "active",
  "tier": "launch",
  "features": {
    "ai_enabled": true,
    "ai_monthly_limit": 10000,
    "billing_enabled": true,
    "custom_domain": true,
    "white_label": false,
    "api_rate_limit": 2000,
    "support_level": "email",
    "mcp_enabled": true
  },
  "quotas": { ... },
  "message": null,
  "next_check_seconds": 300
}

Feature Flag Behavior

Disabled Features

When a feature flag is false, API calls to that service return a structured error:

{
  "error": "feature_disabled",
  "code": "FEATURE_NOT_AVAILABLE",
  "message": "AI features are not available on the sandbox tier",
  "upgrade_url": "https://app.hiveforge.dev/billing"
}

Caching

Feature flags are cached for the duration specified by next_check_seconds (default 300 seconds / 5 minutes). Your application should respect this cache duration to minimize API calls.

// The SDK handles caching automatically
const entitlements = await client.entitlements.check();
// Subsequent calls within 5 minutes return cached data

Tier Changes

When a deployment's tier changes (upgrade or downgrade), the new feature flags take effect after the cache expires. For immediate effect, the SDK provides a force-refresh option:

// Force a fresh check, bypassing cache
const entitlements = await client.entitlements.check({ force: true });

Conditional UI Rendering

Use feature flags to conditionally render UI elements:

function AppLayout({ features }: { features: FeatureFlags }) {
  return (
    <div>
      <MainContent />
 
      {features.ai_enabled && <AIAssistantPanel />}
 
      {features.billing_enabled && <BillingDashboard />}
 
      {features.custom_domain && <DomainSettings />}
 
      {!features.white_label && <PoweredByHiveForge />}
    </div>
  );
}

Always check feature flags server-side before executing privileged operations. Client-side checks improve UX but should not be relied on for access control.

Tier Comparison Quotas & Limits