Skip to content

Config Platform API Overview

This document provides a high-level overview of the Config Platform API surface for configuration management and feature flags. It is written for architects and engineers integrating with the Config Platform.

The Config Platform provides centralized configuration management and feature flag capabilities for multi-tenant SaaS applications. This is a conceptual overview—concrete OpenAPI/Swagger documentation lives in the Config Platform product repository.

Note

This is a conceptual overview of the Config Platform API. Concrete OpenAPI/Swagger documentation with exact endpoints, request/response schemas, and authentication details lives in the Config Platform product repository.

API Surface at a Glance

The Config Platform API provides endpoints for:

  • Configuration Retrieval - Get configuration values for tenants and services
  • Configuration Management - Create, update, and delete configuration
  • Feature Flags - Manage and evaluate feature flags
  • Configuration Snapshots - Capture and restore configuration snapshots
  • Webhooks - Webhook notifications for configuration changes

Authentication and Authorization

Authentication Methods

  • OAuth2/OIDC - Standard OAuth2 client credentials flow
  • API Keys - Service API keys for programmatic access
  • Managed Identity - Azure Managed Identity for Azure-hosted services

Authorization

  • Tenant Isolation - All operations are scoped to tenants
  • Read-Only Access - Read-only access for service consumers
  • Admin Access - Full access for configuration management

See: Identity Platform API Overview for authentication details.

Main Resource Groups

Resource Group Examples Notes
Configuration /config, /config/{key}, /config/tenant/{tenantId} Configuration CRUD operations
Feature Flags /flags, /flags/{key}, /flags/{key}/evaluate Feature flag management
Snapshots /snapshots, /snapshots/{id}, /snapshots/{id}/restore Configuration snapshots
Webhooks /webhooks, /webhooks/{id} Webhook configuration
History /config/{key}/history, /config/{key}/versions Configuration change history

Common Usage Patterns

Pattern 1: Service Fetching Tenant Config at Startup

Steps: 1. Authenticate with service credentials 2. Fetch tenant configuration 3. Cache configuration locally 4. Subscribe to configuration changes 5. Update cache on changes

Example Flow: 

GET /api/v1/config/tenant/{tenantId}
Authorization: Bearer {service_token}

Response: {
  "tenantId": "tenant-123",
  "config": {
    "database.connectionString": "...",
    "feature.newFeature": true,
    "limits.maxUsers": 1000
  },
  "version": "v1.2.3"
}

Webhook: POST /webhooks/config-changed
{
  "tenantId": "tenant-123",
  "key": "feature.newFeature",
  "oldValue": false,
  "newValue": true
}

Pattern 2: Feature Flag Evaluation

Steps: 1. Authenticate with service credentials 2. Evaluate feature flag for tenant/user 3. Use flag value in application logic

Example Flow: 

POST /api/v1/flags/{flagKey}/evaluate
{
  "tenantId": "tenant-123",
  "userId": "user-456",
  "context": {
    "environment": "production",
    "region": "us-east"
  }
}

Response: {
  "enabled": true,
  "value": "variant-a",
  "reason": "tenant-tier-premium"
}

Pattern 3: Configuration Management

Steps: 1. Authenticate with admin credentials 2. Create or update configuration 3. Validate configuration 4. Publish configuration 5. Monitor configuration changes

Example Flow: 

PUT /api/v1/config/{key}
{
  "tenantId": "tenant-123",
  "value": "new-value",
  "description": "Updated configuration",
  "tags": ["production", "critical"]
}

Response: {
  "key": "config.key",
  "value": "new-value",
  "version": "v1.2.4",
  "updatedAt": "2026-01-01T10:30:00Z"
}

Error Handling and Status Codes

Standard HTTP Status Codes

  • 200 OK - Successful request
  • 201 Created - Configuration created successfully
  • 400 Bad Request - Invalid request (e.g., invalid configuration value)
  • 401 Unauthorized - Authentication required
  • 403 Forbidden - Insufficient permissions
  • 404 Not Found - Configuration not found
  • 409 Conflict - Configuration conflict
  • 500 Internal Server Error - Server error
  • 503 Service Unavailable - Service temporarily unavailable

Error Response Format

{
  "error": {
    "code": "INVALID_CONFIG_VALUE",
    "message": "Configuration value validation failed",
    "details": {
      "key": "config.key",
      "value": "invalid-value",
      "validationErrors": ["Value must be a number"]
    }
  }
}

Versioning and Compatibility

API Versioning

  • URL Versioning - /api/v1/, /api/v2/, etc.
  • Configuration Schema Versioning - Version configuration schemas
  • Backward Compatibility - Maintain backward compatibility within major versions

Compatibility

  • Configuration Format - JSON configuration format
  • Feature Flag Format - Standard feature flag format
  • Webhook Payloads - Versioned webhook payloads

Tip

Best Practices: 1. Cache configuration locally 2. Subscribe to configuration changes 3. Validate configuration values 4. Use feature flags for gradual rollouts 5. Monitor configuration changes