Documentation

Everything you need to integrate ConfigDate into your application. Start with the quickstart or explore the API reference.

Quickstart

Get up and running with ConfigDate in under 5 minutes. This guide covers installation, initialization, and fetching your first configuration.

Installation

Install the ConfigDate SDK for Node.js using npm:

npm install @configdate/node

Authentication

Create an API token in the ConfigDate dashboard:

  1. Log into your ConfigDate account
  2. Navigate to Settings → API Tokens
  3. Click "Create Token" and copy the generated token
  4. Store it securely as an environment variable

Initialize the Client

Create a new ConfigDate client in your application:

const ConfigDate = require('@configdate/node');

const client = new ConfigDate.Client({\n apiToken: process.env.CONFIGDATE_TOKEN,\n environment: 'production',\n cacheInterval: 5000 // 5 seconds\n});

Fetch Configuration

Retrieve feature flags and configuration values:

// Get a feature flag
const newCheckout = await client.getFlag('new-checkout');

if (newCheckout.enabled) {\n // Render new checkout UI\n showNewCheckout();\n} else {\n showLegacyCheckout();\n}

// Get configuration value
const apiUrl = await client.getConfig('api-endpoint');
console.log(apiUrl); // "https://api.example.com"

Targeting Rules

Evaluate flags with user context for targeted rollouts:

const variation = await client.getVariation('new-checkout', {\n userId: 'user-123',\n email: 'user@example.com',\n plan: 'premium'\n});

if (variation === 'variant-b') {\n // Show variant B to this user\n}

Next Steps

Concepts

Understanding the core building blocks of ConfigDate will help you design better feature delivery strategies.

Feature Flags

A feature flag is a boolean configuration that controls whether a feature is enabled or disabled. Flags can be toggled in real-time without redeploying your application.

Example use cases:

  • A/B testing new UI designs
  • Gradual rollout of new features
  • Kill switches for problematic features
  • Operational controls for maintenance windows

Environments

Environments allow you to maintain separate configurations for different stages of your application lifecycle. ConfigDate provides predefined environments: Development, Staging, and Production. You can also create custom environments for special use cases.

Each environment has its own set of flags and configurations, letting you test changes safely before deploying to production.

Targeting Rules

Rules determine which users or segments receive a particular flag variation. Rules are evaluated based on user context attributes like user ID, email, plan type, geolocation, and custom properties.

Rule operators supported:

  • equals — Exact match
  • in — Value is in a list
  • contains — String contains substring
  • gt — Greater than (numeric)
  • lt — Less than (numeric)
  • regex — Matches regular expression

Variants

Variants are different values or implementations of a feature flag, used for A/B testing and multivariate experiments. A flag can have multiple variants, and rules determine which variant each user receives.

Example: A flag called checkout-design might have variants current, minimal, and expanded.

Configuration Keys

Beyond boolean flags, ConfigDate stores configuration values as key-value pairs. These can be strings, numbers, JSON objects, or even complex nested structures.

Examples:

  • api-endpoint → "https://api.example.com"
  • max-upload-size → 52428800 (50 MB in bytes)
  • auth-config → {"provider": "oauth2", "timeout": 30}

Segments

Segments are named groups of users that share common attributes. Instead of writing the same rule multiple times, you can create a segment and reference it in multiple flags.

Built-in segments:

  • beta-testers — Users opted into beta programs
  • internal — Your own team members
  • early-adopters — Users who joined in first 30 days

Rollout Percentage

Control the percentage of users who receive a flag, useful for gradual rollouts. You can roll out a flag to 10% of users initially, then increase to 25%, 50%, and finally 100%.

Rollout percentages are deterministic based on user ID, so the same users always see the same variant across sessions.

API Reference

ConfigDate provides a RESTful API for programmatic access to your configurations, flags, and environments. All API requests require authentication with a bearer token.

Authentication

Include your API token in the Authorization header:

curl -H "Authorization: Bearer YOUR_API_TOKEN" https://api.configdate.io/v1/flags

Base URL

https://api.configdate.io/v1

Response Format

All responses are JSON. Successful requests return status code 2xx and failed requests return 4xx or 5xx.

Get All Flags

GET /flags

Retrieve all feature flags in the specified environment.

Query Parameters:
Parameter Type Required Description
environment string No Environment name (default: "production")
limit integer No Max results per page (default: 20, max: 100)
offset integer No Pagination offset (default: 0)
Example Request:
curl -H "Authorization: Bearer YOUR_API_TOKEN" \
"https://api.configdate.io/v1/flags?environment=production&limit=10"

Example Response (200 OK)

{
"success": true,
"data": [
{
"id": "flag-001",
"name": "new-checkout",
"description": "Rollout of redesigned checkout flow",
"enabled": true,
"variants": [
{ "id": "var-a", "name": "variant-a", "rollout": 50 },
{ "id": "var-b", "name": "variant-b", "rollout": 50 }
],
"environment": "production",
"createdAt": "2026-01-15T10:30:00Z",
"updatedAt": "2026-04-22T14:22:33Z"
},
{
"id": "flag-002",
"name": "dark-mode",
"description": "Dark theme for dashboard",
"enabled": true,
"variants": [],
"environment": "production",
"createdAt": "2026-02-03T08:15:22Z",
"updatedAt": "2026-03-10T16:45:11Z"
}
],
"pagination": {
"total": 47,
"limit": 10,
"offset": 0
}
}

Get Flag by Name

GET /flags/{flagName}

Retrieve a specific flag by its name.

Path Parameters:
Parameter Type Description
flagName string The flag name to retrieve
Example Request:
curl -H "Authorization: Bearer YOUR_API_TOKEN" \
"https://api.configdate.io/v1/flags/new-checkout"

Create Flag

POST /flags

Create a new feature flag.

Request Body:
Field Type Required Description
name string Yes Unique flag name (lowercase, hyphens allowed)
description string No Human-readable description
environment string No Environment (default: "production")
enabled boolean No Initial state (default: false)
variants array No Array of variant objects
Example Request:
curl -X POST \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{\
"name": "new-search",\
"description": "Advanced search with filters",\
"environment": "production",\
"enabled": false,\
"variants": [\
{ "name": "control", "rollout": 50 },\
{ "name": "treatment", "rollout": 50 }\
]\
}' \
https://api.configdate.io/v1/flags

Example Response (201 Created)

{
"success": true,
"data": {
"id": "flag-003",
"name": "new-search",
"description": "Advanced search with filters",
"enabled": false,
"variants": [
{ "id": "var-ctrl", "name": "control", "rollout": 50 },
{ "id": "var-trt", "name": "treatment", "rollout": 50 }
],
"environment": "production",
"createdAt": "2026-05-05T09:20:15Z",
"updatedAt": "2026-05-05T09:20:15Z"
}
}

Update Flag

PUT /flags/{flagName}

Update an existing flag's properties, variants, or targeting rules.

Example Request:
curl -X PUT \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{\
"enabled": true,\
"description": "Advanced search with AI suggestions"\
}' \
https://api.configdate.io/v1/flags/new-search

Delete Flag

DELETE /flags/{flagName}

Permanently delete a feature flag. This action cannot be undone.

Example Request:
curl -X DELETE \
-H "Authorization: Bearer YOUR_API_TOKEN" \
https://api.configdate.io/v1/flags/new-search

Example Response (204 No Content)

No response body on success.

Get Configuration Value

GET /config/{configKey}

Retrieve a configuration value by key.

Example Request:
curl -H "Authorization: Bearer YOUR_API_TOKEN" \
https://api.configdate.io/v1/config/api-endpoint

Example Response (200 OK)

{
"success": true,
"data": {
"key": "api-endpoint",
"value": "https://api.configdate.io",
"environment": "production",
"type": "string"
}
}

Evaluate Flag with Context

POST /flags/{flagName}/evaluate

Evaluate a flag against a user context to determine enabled state and variant.

Request Body:
{
"userId": "user-123",
"email": "user@example.com",
"plan": "premium",
"custom": {\
"region": "us-west",\
"signupDate": "2025-06-15"\
}\
}

Example Response (200 OK)

{
"success": true,
"data": {
"flagName": "new-checkout",
"enabled": true,
"variant": "variant-b",
"reason": "targeted rule matched for premium users"
}
}

Error Responses

The API uses standard HTTP status codes. Errors include a message explaining what went wrong.

400 Bad Request

{
"success": false,
"error": "Invalid flag name: must use lowercase letters, numbers, and hyphens"\
}

401 Unauthorized

{
"success": false,
"error": "Missing or invalid API token"\
}

404 Not Found

{
"success": false,
"error": "Flag 'missing-flag' not found"\
}

429 Rate Limited

{
"success": false,
"error": "Rate limit exceeded. Retry after 60 seconds",
"retryAfter": 60\
}

SDKs & Libraries

ConfigDate provides official SDKs for all major programming languages. Choose your language and follow the integration guide.

Node.js

@configdate/node

npm install @configdate/node
View docs →

Python

configdate-python

pip install configdate-python
View docs →

Go

github.com/configdate/go-sdk

go get github.com/configdate/go-sdk
View docs →

Rust

configdate

[dependencies]
configdate = "1.0"
View docs →

Swift

ConfigDate

.package(url: "...")
View docs →

Kotlin

io.configdate:sdk

implementation 'io.configdate:sdk:1.0.0'
View docs →

Node.js SDK

The official Node.js SDK provides seamless integration for backend and frontend applications.

Installation:
npm install @configdate/node
Initialize:
const ConfigDate = require('@configdate/node');

const client = new ConfigDate.Client({\n apiToken: process.env.CONFIGDATE_TOKEN,\n environment: 'production'\n});
Usage:
// Boolean flag
const enabled = await client.getFlag('feature-name');

// Get value
const value = await client.getConfig('config-key');

// Evaluate with context
const variant = await client.getVariation('flag-name', {\n userId: 'user-123'\n});

Python SDK

The Python SDK is designed for Django, FastAPI, Flask, and pure async applications.

Installation:
pip install configdate-python
Initialize:
from configdate import ConfigDate

client = ConfigDate(\n api_token="YOUR_TOKEN",\n environment="production"\n)
Usage:
# Boolean flag
enabled = client.get_flag('feature-name')

# Get value
value = client.get_config('config-key')

# Evaluate with context
variant = client.get_variation(\n 'flag-name',\n { 'user_id': 'user-123' }\n)

Go SDK

The Go SDK is performant and thread-safe, perfect for microservices.

Installation:
go get github.com/configdate/go-sdk
Initialize:
package main

import "github.com/configdate/go-sdk"

client := configdate.NewClient(&configdate.Config{\n APIToken: "YOUR_TOKEN",\n Environment: "production",\n})

Rust SDK

The Rust SDK prioritizes performance and safety for systems programming.

Add to Cargo.toml:
[dependencies]
configdate = "1.0"
tokio = { version = "1", features = ["full"] }

Swift SDK

Integrate ConfigDate into your iOS, macOS, tvOS, and watchOS apps.

SPM:
.package(url: "https://github.com/configdate/swift-sdk.git", from: "1.0.0")

Kotlin SDK

The Kotlin SDK integrates seamlessly with Android and JVM applications.

Gradle:
implementation 'io.configdate:sdk:1.0.0'

SDK Feature Comparison

Feature Node.js Python Go Rust Swift Kotlin
Local Caching ✓ ✓ ✓ ✓ ✓ ✓
Async/Await ✓ ✓ ✓ ✓ ✓ ✓
Streaming ✓ ✓ ✓ ✓ — —
Webhooks ✓ ✓ ✓ ✓ ✓ ✓
Offline Mode ✓ ✓ ✓ ✓ ✓ ✓

Webhooks

Webhooks allow ConfigDate to push real-time updates to your application when flags, configurations, or environments change. This eliminates the need to poll the API.

Setting Up Webhooks

  1. Go to Settings → Webhooks in your ConfigDate dashboard
  2. Click "New Webhook"
  3. Enter your endpoint URL (must be HTTPS)
  4. Select the events you want to receive
  5. Add custom headers if needed (e.g., for authentication)
  6. Click Create

Webhook Events

ConfigDate supports the following webhook event types:

flag.created

Fired when a new feature flag is created.

Payload:
{
"event": "flag.created",
"timestamp": "2026-05-05T10:30:00Z",
"data": {\n "id": "flag-123",
"name": "beta-feature",\n "description": "New beta feature",\n "environment": "production"
}\n}

flag.updated

Fired when a flag's configuration is modified.

Payload:
{
"event": "flag.updated",
"timestamp": "2026-05-05T11:15:22Z",
"data": {\n "id": "flag-123",
"name": "beta-feature",\n "changes": [\n { "field": "enabled", "from": false, "to": true }\n ]\n }\n}

flag.deleted

Fired when a feature flag is deleted.

environment.created

Fired when a new environment is created.

environment.updated

Fired when an environment's settings change.

config.updated

Fired when a configuration value is changed.

rule.created

Fired when a targeting rule is created for a flag.

rule.updated

Fired when a targeting rule is modified.

Webhook Signing

All webhooks are signed with HMAC-SHA256 using your webhook secret. Verify the signature to ensure the request came from ConfigDate.

The signature is provided in the X-ConfigDate-Signature header:

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {\n const hash = crypto\n .createHmac('sha256', secret)\n .update(payload)\n .digest('hex');\n return hash === signature;\n}

Webhook Delivery

ConfigDate sends webhooks as HTTP POST requests with a JSON body. We retry failed deliveries with exponential backoff (up to 3 times over 24 hours).

Expected Response: Your endpoint should return 2xx status code within 30 seconds.

Webhook History

View webhook delivery logs and retry failed deliveries from the Webhooks page in your dashboard.

Security

ConfigDate is built with security as a core principle. Your configurations and flags are encrypted, stored securely, and delivered over HTTPS with authentication on every request.

API Token Security

Treat API tokens like passwords. Never commit them to version control or expose them in client-side code.

  • Store tokens in environment variables or secrets management systems
  • Rotate tokens regularly (we recommend every 90 days)
  • Create separate tokens for different environments (development, staging, production)
  • Use tokens with minimal required permissions
  • Revoke tokens immediately if compromised

Token Rotation

To rotate an API token:

  1. Generate a new token in Settings → API Tokens
  2. Update your applications to use the new token
  3. Wait for all applications to restart with the new token
  4. Revoke the old token

IP Allowlisting

Restrict API access to specific IP addresses using IP allowlists. This adds an extra layer of security for enterprise accounts.

To enable:

  1. Go to Settings → Security
  2. Enable "IP Allowlist"
  3. Add your application server IP addresses
  4. Requests from other IPs will be rejected

Encryption at Rest

All configurations and secrets are encrypted at rest using AES-256-GCM. Encryption keys are managed separately and rotated automatically.

Encryption in Transit

All communication with ConfigDate APIs is encrypted using TLS 1.2 or higher. We enforce HTTPS-only connections.

Data Retention and Deletion

You can request deletion of your account and associated data at any time. ConfigDate will securely erase all data within 30 days of the request.

Compliance

ConfigDate is compliant with:

  • SOC 2 Type II
  • GDPR
  • CCPA
  • HIPAA (available on Enterprise plan)

Audit Logging

All changes to flags, rules, and configurations are logged with user, timestamp, and action details. Audit logs are retained for 1 year and available in the dashboard.

Reporting Security Issues

If you discover a security vulnerability, please email security@configdate.io instead of using the public issue tracker. We appreciate responsible disclosure.

Troubleshooting

Common issues and solutions when using ConfigDate.

SDK Fails to Initialize

Problem: "Invalid API token" or "Authentication failed" error.

Solution:

  • Verify your API token is correct and not expired
  • Check that the token is properly set in your environment variable
  • Ensure you're using the correct environment (production, staging, etc.)
  • Try creating a new token in the dashboard

Flags Return Null or Undefined

Problem: SDK returns null when calling getFlag().

Solution:

  • Verify the flag exists in the dashboard
  • Check that you're using the correct flag name (case-sensitive)
  • Ensure the flag exists in the environment you're querying
  • Check your internet connection and API rate limits

Slow Flag Evaluation

Problem: Flag evaluation is taking >100ms.

Solution:

  • Enable local caching in your SDK configuration
  • Check your network latency to ConfigDate API
  • Use edge endpoints instead of central API for lower latency
  • Evaluate multiple flags in a batch if possible

Webhooks Not Receiving Events

Problem: Webhook events are not being delivered.

Solution:

  • Verify your webhook URL is reachable from the internet
  • Check that your endpoint returns 2xx status code
  • Review webhook logs in the dashboard for error details
  • Verify the webhook is subscribed to the correct events
  • Check for firewall rules blocking incoming requests

High API Usage / Rate Limits

Problem: Getting "Rate limit exceeded" errors.

Solution:

  • Enable local caching to reduce API calls
  • Use longer cache intervals if stale data is acceptable
  • Batch flag evaluations where possible
  • Contact support if you need higher rate limits

Targeting Rules Not Working

Problem: Targeting rules aren't selecting the correct users.

Solution:

  • Verify user context is being passed to getVariation()
  • Check rule conditions match your user attributes
  • Test rules with specific user IDs in the dashboard
  • Review rule evaluation logs in Settings → Audit Log

Still Need Help?

Contact our support team at support@configdate.io or visit our community forum.