Overview

Feature Config is a powerful feature flag management system that allows you to control, test, and rollout features with confidence.

What is Feature Config?

Feature Config enables you to:

• Control feature rollouts - Safely deploy features to specific users or percentages of your user base
• A/B test features - Compare different versions of features and measure their impact
• Manage configurations - Centralize application settings and feature toggles in one place
• Target users - Show different features based on user context (location, plan, custom attributes)
• Real-time updates - Change features instantly without code deployments or app updates
• Multi-environment support - Manage dev, staging, and production configurations independently

💡 Key Benefits

Common Use Cases

• Gradual Rollouts: Release features to 10% of users, then gradually increase to 100%
• Beta Testing: Give early access to specific users or user groups
• A/B Testing: Show different feature variations to measure effectiveness
• Regional Features: Enable features only in specific countries or regions
• Premium Features: Show advanced features only to paid users
• Kill Switches: Quickly disable features causing performance issues
• Environment Promotion: Test in dev, validate in staging, release to production
• Configuration Management: Manage API endpoints, limits, and settings without code changes

Quick Start Guide

Get up and running with Feature Config in four simple steps:

Key Concepts

Understanding these core concepts will help you make the most of Feature Config.

Dashboard

The dashboard provides an overview of your Feature Config system and quick access to common tasks.

What You'll See

• Getting Started Guide: Step-by-step instructions for new users
• Statistics: Total sites, environments, features, users, and active tokens
• Quick Actions: Fast access to create sites, add users, and test features
• Recent Activity: Shows recent changes from audit logs
• System Health: Database and cache status

Sites

Sites represent your applications or services. They provide top-level organization and ownership.

Creating Sites

1. Click "Create Site" on the Sites page
2. Enter a name and optional description
3. Site is created with an auto-generated "prod" environment
4. Click "Create Site" to complete

Site Navigation

Navigate through your sites with ease:

• Click any site row to navigate to its environments
• Use the hamburger menu (⋮) for site actions (edit, delete, etc.)
• Context is preserved as you navigate between pages
• Owner information shows who created and owns the site

Site Ownership

Every site has an owner:

• Owner is set to the user who created the site
• Provides clear accountability and audit trail
• Foundation for permission model
• Can be transferred to another user if needed

Environments

Environments are deployment targets within a site (e.g., dev, staging, prod). They enable independent configuration per environment.

Creating Environments

1. Select a site from the dropdown
2. Click "Create Environment"
3. Enter a name (lowercase, alphanumeric, underscore, or hyphen only)
4. Add optional description and tags
5. Set initial status (active, archived, maintenance)
6. Click "Create Environment"

Environment Status

• Active: Normal operation, accepting feature requests
• Archived: Inactive, preserved for historical reference
• Maintenance: Temporarily unavailable, planned maintenance

Environment Limits

Each site can have up to 10 environments (configurable via MAX_ENVIRONMENTS setting).

Environment-Scoped Features

The same feature key can have different values per environment:

• Test new features in dev without affecting prod
• Gradually roll out features from dev → staging → prod
• Each environment has independent rules and configurations
• Use environment-specific tokens for secure access

Features

Features are configuration values scoped to both site AND environment. They can be toggles, settings, or any configurable value.

Feature Types

• STRING: Text values (e.g., "Welcome to our app!")
• NUMBER: Numeric values (e.g., 42, 3.14)
• BOOLEAN: True/false values (e.g., true, false)
• JSON: Complex objects (e.g., {"theme": "dark", "size": "large"})

Creating Features

1. Select a site and environment from the dropdowns
2. Click "Create Feature"
3. Enter a unique key name
4. Choose the appropriate type
5. Set the default value
6. Add a description and tags (optional)
7. Click "Create Feature"

Feature Navigation

Navigate through your features seamlessly:

• Click any feature row to navigate to its rules
• Use the hamburger menu (⋮) for feature actions (edit, delete, etc.)
• Context is preserved - your selected site and environment remain active
• Enable/Disable toggle for quick feature activation control

Environment-Specific Features

Features are scoped to both site and environment:

• Same feature key can exist in multiple environments with different values
• Example: "new_checkout" = true in dev, false in prod
• Promotes features through environments as they're validated
• Each environment's features are completely independent

Rule Builder

The Rule Builder allows you to create sophisticated targeting rules that determine when and how features are shown to users.

Rule Components

• Priority: Higher numbers take precedence (1-100)
• Conditions: Logic that determines when the rule applies (optional)
• Rollout: Percentage of matching users who get this rule (optional)
• Outcome: The value to return when the rule matches

Condition Types

• Equals: Exact match (e.g., country = "US")
• Not Equals: Does not match (e.g., plan ≠ "free")
• Contains: String contains value (e.g., email contains "@company.com")
• Greater/Less Than: Numeric comparisons (e.g., age > 18)
• In/Not In: Value in list (e.g., country in ["US", "CA", "MX"])

Complex Conditions

You can combine conditions using AND/OR logic:

• AND: All conditions must be true
• OR: Any condition can be true
• Nested: Combine AND/OR groups for complex logic

Rollout-Only Rules

You can create rules with only percentage rollouts (no conditions):

• Example: "50% of all users get true"
• Useful for gradual rollouts without targeting
• Deterministic - same user always gets same result
• Based on SHA-256 hashing of userId + feature key

Test Console

The Test Console allows you to test your feature configurations with different user contexts without affecting real users.

How to Test

1. Select a site and environment
2. Select a feature to test
3. Enter test context (user properties) in JSON format
4. Optionally specify a user ID for consistent testing
5. Click "Test Evaluation"

Test Results

The console shows you:

• Evaluated Value: What the user would receive
• Matched Rule: Which rule (if any) was applied
• Decision ID: Unique identifier for this evaluation
• Rollout Status: Whether the user was included in percentage rollouts
• Cache Status: Whether result was served from cache

Analytics

Feature Analytics provides privacy-first insights into how your features are being evaluated and used.

What's Tracked

• Feature Evaluations: How many times each feature was evaluated
• Context Fields: Only fields actually checked by rules (privacy-first)
• Rule Performance: Which rules are matching and how often
• Trends Over Time: Daily aggregations showing usage patterns

Privacy-First Design

Analytics are designed with GDPR compliance in mind:

• Minimal Data Collection: Only context fields checked by rules
• No PII by Default: User IDs are hashed (SHA-256)
• Configurable Sampling: Reduce data volume while maintaining accuracy
• Short Retention: Configurable retention periods (default 90 days)
• Field Exclusion: Exclude sensitive fields from analytics

Analytics Dashboard

The analytics page shows:

• Summary Cards: Total evaluations, unique users, avg evaluations per user
• Trend Charts: Daily evaluation counts over time (Chart.js)
• Context Breakdown: Top context field values being evaluated
• Rule Performance: Which rules are matching most often

Performance Impact

• Fire-and-Forget API: Analytics calls don't block feature evaluation
• Batching: Client SDK batches 20 evaluations or 60 seconds
• Async Processing: Redis queue with background workers
• Low Overhead: <50ms API response time

Webhooks

Webhooks allow you to receive real-time notifications when features, rules, or configurations change.

Webhook Events

Webhooks are triggered for these events:

• Feature Created: New feature added to an environment
• Feature Updated: Feature value or settings changed
• Feature Deleted: Feature removed from environment
• Rule Created: New rule added to a feature
• Rule Updated: Rule conditions or outcome changed
• Rule Deleted: Rule removed from feature

Creating Webhooks

1. Navigate to Webhooks page
2. Click "Create Webhook"
3. Enter a name and description
4. Provide the target URL (must be HTTPS in production)
5. Select which events to subscribe to
6. Optionally set a secret for signature verification
7. Click "Create Webhook"

Webhook Payload

Each webhook request includes:

{
  "event": "feature.updated",
  "timestamp": "2025-10-18T12:00:00Z",
  "siteId": "uuid",
  "environmentId": "uuid",
  "data": {
    "feature": {...},
    "changes": {...}
  }
}

Security

• Secret Tokens: Verify webhook authenticity with HMAC-SHA256 signatures
• HTTPS Only: Production webhooks require secure connections
• Retry Logic: Failed deliveries are retried with exponential backoff
• Signature Header: X-Webhook-Signature header contains HMAC signature

Testing Webhooks

Use the built-in testing tools:

• Test Button: Send a test payload to your webhook
• Delivery Logs: View recent webhook deliveries and responses
• Test Payloads: See example payloads for each event type

User Management

User management allows you to control access to the Feature Config admin interface with role-based permissions.

User Roles

• Admin: Full access to all features including user management, 2FA administration, and GDPR requests
• Editor: Can create and modify sites, environments, features, and rules
• Viewer: Read-only access to view configurations

Creating Users

1. Click "Add User" on the Users page (admin only)
2. Enter username, email, and password
3. Select appropriate role
4. Click "Create User"
5. User will receive a welcome email (if email configured)

Two-Factor Authentication

Admin users are required to enable 2FA:

• Grace Period: 7 days to enable 2FA from account creation
• Methods: TOTP (authenticator app) or email codes
• Mandatory: After grace period, admins must enable 2FA to access dashboard
• Backup Codes: Generated for account recovery

Managing Users

Use the modern interface to manage users:

• Hamburger menu (⋮): Edit, change role, reset 2FA, delete user
• Search: Filter users by username or email (server-side search)
• Privacy: Email addresses hidden from list view (data minimization)

API Tokens

API tokens provide secure, environment-scoped access for your applications to fetch feature configurations.

Environment-Scoped Tokens

Tokens are scoped to specific environments for security:

• Format: alm_env_{sitename}_{envname}_{random}
• Isolation: Dev tokens cannot access prod data
• Security: Each environment has its own tokens
• Traceability: Token usage is tracked per environment

Creating Tokens

1. Select a site and environment
2. Click "Create Token"
3. Enter a description (e.g., "Mobile App - Dev")
4. Set expiration date (optional)
5. Click "Create Token"
6. Copy token immediately - it won't be shown again

Token Security

• SHA-256 Hashing: Tokens are hashed before storage
• One-time Display: Plaintext token shown only at creation
• Rate Limiting: 100 requests/minute per token
• Expiration: Optional expiration dates for temporary access

Using Tokens

Include the token in your API requests:

curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://features.almiro.se/api/v1/sites/{siteId}/environments/{envId}/features

Managing Tokens

Use the modern interface to manage tokens:

• Hamburger menu (⋮): Edit description, copy token, delete token
• Filter by environment: View tokens for specific environments
• Expiration tracking: See when tokens will expire
• Usage statistics: Monitor token usage per environment

Two-Factor Authentication (2FA)

Two-Factor Authentication adds an extra layer of security to your Feature Config account.

Available Methods

• TOTP (Time-based One-Time Password): Use authenticator apps like Google Authenticator, Authy, or 1Password
• Email Codes: Receive 6-digit codes via email (valid for 10 minutes)

Setting Up TOTP

1. Navigate to Profile page
2. Click "Enable 2FA"
3. Select "Authenticator App"
4. Scan QR code with your authenticator app
5. Enter 6-digit verification code
6. Save backup codes securely

Setting Up Email 2FA

1. Navigate to Profile page
2. Click "Enable 2FA"
3. Select "Email Codes"
4. Verify your email address
5. Enter confirmation code sent to email
6. Save backup codes securely

Login with 2FA

When 2FA is enabled:

1. Enter username and password
2. Enter 6-digit 2FA code (from app or email)
3. Optionally check "Trust this device for 30 days"
4. Click "Verify" to complete login

Trusted Devices

• 30-day Trust: Skip 2FA on trusted devices for 30 days
• Revoke Access: Remove trusted devices from Profile page
• Audit Trail: View all trusted devices with last used timestamps

Backup Codes

Backup codes provide account recovery if you lose access to your 2FA method:

• 8 single-use codes generated when enabling 2FA
• Use any backup code in place of 2FA code
• Each code can only be used once
• Generate new codes from Profile page

Admin 2FA Management

Admins can manage 2FA for all users:

• View Statistics: See 2FA adoption rates
• Disable 2FA: Reset 2FA for locked-out users
• Send Reminders: Remind users to enable 2FA
• Enforce 2FA: Require 2FA for all admin users

GDPR Data Subject Rights

Feature Config provides built-in support for GDPR data subject rights requests (access, erasure, portability).

Available Request Types

• Access Request (Art. 15): Export all personal data for a user
• Erasure Request (Art. 17): Delete all personal data for a user ("Right to be Forgotten")
• Portability Request (Art. 20): Export data in machine-readable format (JSON)

Creating a GDPR Request

1. Navigate to GDPR Requests page (admin only)
2. Click "Create Request"
3. Enter user identifier (username or email)
4. Select request type
5. Add optional notes
6. Click "Submit Request"

Request Processing

Requests are processed automatically:

• Access/Portability: JSON file generated with all user data
• Erasure: User data anonymized or deleted (preserves referential integrity)
• Email Notification: User notified when request is complete
• Auto-Cleanup: Export files deleted after 30 days

What Data is Included

GDPR exports include:

• User account information (username, email, role)
• Sites owned by the user
• Audit log entries (actions performed)
• 2FA settings and trusted devices
• GDPR request history

Request Status

• Pending: Request submitted, awaiting processing
• Completed: Request processed successfully
• Failed: Request processing encountered an error

White-Label / Branding

Customize the look and feel of Feature Config to match your brand with white-label branding options.

Branding Options

• Colors: Primary, secondary, accent, success, warning, error, info colors
• Alert Text Colors: Text colors for alert backgrounds (success, warning, error, info)
• Typography: Font families for headings and body text
• Logo: Custom logo URL
• Favicon: Custom favicon URL
• Company Name: Your organization name

Applying Branding

Branding is applied at the site level:

1. Navigate to Sites page
2. Select site to customize
3. Open hamburger menu (⋮)
4. Click "Edit Branding"
5. Customize colors, fonts, and assets
6. Preview changes in real-time
7. Click "Save Branding"

Color Customization

Customize all interface colors:

• Primary Color: Main brand color for buttons, links
• Secondary Color: Supporting color for secondary actions
• Accent Color: Highlight color for important elements
• Success/Warning/Error: Alert background colors
• Success/Warning/Error Text: Alert text colors for proper contrast
• Background Colors: Primary, secondary, tertiary backgrounds
• Text Colors: Primary, secondary, muted text

WCAG Compliance

Branding includes WCAG contrast validation:

• Automatically checks color contrast ratios
• Warns about accessibility issues
• Ensures text remains readable with custom colors
• Validates alert text colors against background colors

Integration Overview

Learn how to integrate Feature Config into your applications with practical code examples and best practices.

Quick Links

Integration Pattern

All integrations follow this pattern:

1. Initialize client with API token and base URL
2. Fetch features for specific site + environment + context
3. Evaluate features client-side for low latency
4. Cache results for 5 minutes to reduce API calls
5. Handle errors gracefully with default values

Frontend Integration

Choose the integration method that best fits your application:

📦 Vanilla JavaScript (No Dependencies)

Use our standalone JavaScript client - perfect for any web project!

Option 1: Link from your server

<script src="https://features.almiro.se/feature-config.js"></script>
<script>
  const client = new FeatureConfigClient({
    apiToken: 'your-token-here',
    baseUrl: 'https://features.almiro.se/api/v1'
  });

  // Get all features for site + environment
  client.getFeatures('site-id', 'env-id', { userId: '123', plan: 'premium' })
    .then(features => console.log(features));

  // Get specific feature
  client.getFeature('site-id', 'env-id', 'welcome_message', 'Hello!', { userId: '123' })
    .then(value => console.log(value));

  // Check if feature is enabled
  client.isFeatureEnabled('site-id', 'env-id', 'new_ui', { userId: '123' })
    .then(enabled => console.log('New UI:', enabled));
</script>

Option 2: Download and self-host

Download the client file and include it in your project:

<script src="/js/feature-config.js"></script>
<script>
  const client = new FeatureConfigClient({
    apiToken: 'your-token-here',
    baseUrl: 'https://features.almiro.se/api/v1'
  });
</script>

⚛️ React Integration

For React applications, use a custom hook for better integration:

1. Install Dependencies

npm install axios

2. Create Feature Config Hook

// hooks/useFeatureConfig.js
import { useState, useEffect } from 'react';
import axios from 'axios';

const API_BASE = 'https://features.almiro.se/api/v1';
const API_TOKEN = process.env.REACT_APP_FEATURE_CONFIG_TOKEN;

export const useFeatureConfig = (siteId, environmentId, context = {}) => {
  const [features, setFeatures] = useState({});
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState(null);

  useEffect(() => {
    const fetchFeatures = async () => {
      try {
        setLoading(true);
        const response = await axios.post(`${API_BASE}/evaluate`, {
          siteId,
          environmentId,
          context
        }, {
          headers: {
            'Authorization': `Bearer ${API_TOKEN}`,
            'Content-Type': 'application/json'
          }
        });
        
        setFeatures(response.data.features || {});
        setError(null);
      } catch (err) {
        setError(err.message);
        console.error('Failed to fetch features:', err);
      } finally {
        setLoading(false);
      }
    };

    fetchFeatures();
  }, [siteId, environmentId, JSON.stringify(context)]);

  const getFeature = (key, defaultValue = null) => {
    return features[key]?.value ?? defaultValue;
  };

  const isFeatureEnabled = (key) => {
    return getFeature(key, false) === true;
  };

  return { features, loading, error, getFeature, isFeatureEnabled };
};

3. Use in Your Components

// components/WelcomeMessage.js
import React from 'react';
import { useFeatureConfig } from '../hooks/useFeatureConfig';

const WelcomeMessage = ({ user }) => {
  const { getFeature, isFeatureEnabled, loading } = useFeatureConfig(
    'your-site-id',
    'prod',  // environment
    {
      userId: user.id,
      plan: user.plan,
      country: user.country
    }
  );

  if (loading) return 
Loading...
;

  const welcomeMessage = getFeature('welcome_message', 'Welcome!');
  const showPremiumBanner = isFeatureEnabled('premium_banner');

  return (
    

      
{welcomeMessage}
      {showPremiumBanner && 
🎉 You have premium access!
}
    
  );
};

export default WelcomeMessage;

Backend Integration (Node.js/Express)

Here's how to integrate Feature Config into your Node.js backend with caching:

1. Create Feature Config Service

// services/FeatureConfigService.js
const axios = require('axios');

class FeatureConfigService {
  constructor(apiToken, baseUrl = 'https://features.almiro.se/api/v1') {
    this.apiToken = apiToken;
    this.baseUrl = baseUrl;
    this.cache = new Map();
    this.cacheTimeout = 5 * 60 * 1000; // 5 minutes
  }

  async getFeatures(siteId, environmentId, context = {}) {
    const cacheKey = `${siteId}:${environmentId}:${JSON.stringify(context)}`;
    const cached = this.cache.get(cacheKey);
    
    if (cached && Date.now() - cached.timestamp < this.cacheTimeout) {
      return cached.data;
    }

    try {
      const response = await axios.post(`${this.baseUrl}/evaluate`, {
        siteId,
        environmentId,
        context
      }, {
        headers: {
          'Authorization': `Bearer ${this.apiToken}`,
          'Content-Type': 'application/json'
        }
      });

      const features = response.data.features || {};
      
      // Cache the result
      this.cache.set(cacheKey, {
        data: features,
        timestamp: Date.now()
      });

      return features;
    } catch (error) {
      console.error('Failed to fetch features:', error);
      return {};
    }
  }

  async getFeature(siteId, environmentId, key, defaultValue = null, context = {}) {
    const features = await this.getFeatures(siteId, environmentId, context);
    return features[key]?.value ?? defaultValue;
  }

  async isFeatureEnabled(siteId, environmentId, key, context = {}) {
    return await this.getFeature(siteId, environmentId, key, false, context) === true;
  }
}

module.exports = FeatureConfigService;

2. Use in Express Routes

// routes/api.js
const express = require('express');
const FeatureConfigService = require('../services/FeatureConfigService');

const router = express.Router();
const featureConfig = new FeatureConfigService(process.env.FEATURE_CONFIG_TOKEN);

router.get('/dashboard', async (req, res) => {
  const context = {
    userId: req.user?.id,
    plan: req.user?.plan,
    country: req.user?.country
  };

  const showNewDashboard = await featureConfig.isFeatureEnabled(
    'your-site-id',
    'prod',
    'new_dashboard',
    context
  );
  
  const maxItems = await featureConfig.getFeature(
    'your-site-id',
    'prod',
    'dashboard_max_items',
    10,
    context
  );

  res.render(showNewDashboard ? 'dashboard-v2' : 'dashboard-v1', { maxItems });
});

module.exports = router;

Python Integration

Here's a simple Python client for Feature Config:

# feature_config.py
import requests
import json
import time
from typing import Dict, Any

class FeatureConfigClient:
    def __init__(self, api_token: str, base_url: str = "https://features.almiro.se/api/v1"):
        self.api_token = api_token
        self.base_url = base_url
        self.cache = {}
        self.cache_timeout = 300  # 5 minutes

    def get_features(self, site_id: str, environment_id: str, context: Dict[str, Any] = None) -> Dict[str, Any]:
        if context is None:
            context = {}
            
        cache_key = f"{site_id}:{environment_id}:{json.dumps(context, sort_keys=True)}"
        
        if cache_key in self.cache:
            cached = self.cache[cache_key]
            if time.time() - cached['timestamp'] < self.cache_timeout:
                return cached['data']

        try:
            response = requests.post(
                f"{self.base_url}/evaluate",
                json={"siteId": site_id, "environmentId": environment_id, "context": context},
                headers={
                    "Authorization": f"Bearer {self.api_token}",
                    "Content-Type": "application/json"
                },
                timeout=5
            )
            response.raise_for_status()
            
            features = response.json().get('features', {})
            
            self.cache[cache_key] = {
                'data': features,
                'timestamp': time.time()
            }
            
            return features
        except Exception as e:
            print(f"Failed to fetch features: {e}")
            return {}

    def get_feature(self, site_id: str, environment_id: str, key: str, default_value: Any = None, context: Dict[str, Any] = None) -> Any:
        features = self.get_features(site_id, environment_id, context)
        return features.get(key, {}).get('value', default_value)

    def is_feature_enabled(self, site_id: str, environment_id: str, key: str, context: Dict[str, Any] = None) -> bool:
        return self.get_feature(site_id, environment_id, key, False, context) is True

# Usage example
if __name__ == "__main__":
    client = FeatureConfigClient(api_token="your-token-here")
    
    context = {"userId": "123", "plan": "premium"}
    enabled = client.is_feature_enabled("site-id", "prod", "new_feature", context)
    print(f"New feature enabled: {enabled}")

Integration Best Practices

Environment Setup

# .env file
FEATURE_CONFIG_TOKEN=your_token_here
FEATURE_CONFIG_URL=https://features.almiro.se/api/v1
FEATURE_CONFIG_SITE_ID=your-site-id
FEATURE_CONFIG_ENV=prod

Best Practices Checklist