Configuration
System-wide settings with encryption, visibility controls, and group-based access.
What Is System Configuration?
System configuration is the platform's centralized key-value store for settings that govern how the platform behaves. Configuration values control everything from authentication provider settings and storage connection details to email delivery parameters and third-party integration credentials. They are the knobs and switches that administrators use to tune a deployment without modifying code or redeploying services.
Unlike environment variables or static config files, system configuration is managed through the platform's administration interface. Changes take effect at runtime — services read configuration values as they need them, so most changes do not require a restart.
Configuration Properties
Each configuration entry has several properties that control how it behaves:
| Property | Description |
|---|---|
| Key | A unique identifier for the configuration value. Keys typically follow a hierarchical naming convention using dots or slashes to indicate the area they belong to. |
| Value | The actual setting data. Can be a string, number, JSON object, or any text-based value. Sensitive values are stored encrypted. |
| Description | A human-readable explanation of what the configuration value controls and what values are acceptable. Helps administrators understand each setting without consulting external documentation. |
| Public / Private flag | Controls whether the configuration value is readable by all authenticated users (public) or restricted to users with explicit permission (private). |
Encrypted Values
Configuration values that contain sensitive data — API keys, OAuth client secrets, database passwords, encryption keys, SMTP credentials — are encrypted at rest. The platform uses nonce-based encryption to protect these values, ensuring that each encrypted value has a unique nonce and cannot be decrypted without the platform's encryption key.
Key aspects of the encryption system:
- Transparent decryption. Services and scripts that read configuration values through the platform API receive the decrypted value automatically. They do not need to know whether a value is encrypted or plaintext.
- Nonce-based encryption. Each encrypted value uses a unique nonce, ensuring that even identical plaintext values produce different ciphertext. This prevents pattern analysis attacks.
- Separate key management. The encryption key is stored separately from the encrypted data, typically as an environment variable or in a secrets management service. Accessing the configuration database alone is not sufficient to decrypt sensitive values.
- Selective encryption. Not all configuration values need encryption. Only values explicitly marked as sensitive are encrypted. Non-sensitive values are stored in plaintext for easier debugging and inspection.
Group-Based Access Control
Access to individual configuration values is controlled through the same group-based permission system used across the rest of the platform. Administrators can specify which groups are allowed to read or modify specific configuration values.
- Read access. Determines which groups can see the value of a configuration entry. Useful for restricting access to credentials that should only be visible to specific services or administrators.
- Write access. Determines which groups can modify the value. This allows you to delegate management of specific settings to team leads or service owners without granting full administrative access.
- Admin-only defaults. By default, all configuration values are readable and writable only by the admin group. Access must be explicitly granted to other groups.
This granular access control is especially important in organizations where different teams manage different aspects of the platform. A marketing team might manage email delivery settings, while a security team controls authentication provider configuration, and neither group needs access to the other's settings.
Public vs. Private Configuration
The public/private flag provides a broad visibility control that works alongside group-based permissions:
- Public configuration. Values marked as public are readable by any authenticated user of the platform. These are settings that applications and services need to function but that do not contain sensitive information — feature flags, display settings, supported locale lists, default pagination sizes, and similar operational parameters.
- Private configuration. Values marked as private are only readable by users in groups that have been explicitly granted read access. This is the appropriate setting for API keys, database credentials, encryption secrets, and any value that should not be broadly accessible.
Configuration Categories
While configuration values are stored as a flat key-value structure, they are typically organized into logical categories by key naming convention. Common categories include:
| Category | Typical Settings |
|---|---|
| Authentication | OAuth provider settings, JWT signing keys, session duration, allowed redirect URIs, social login provider credentials. |
| Storage | S3 bucket names, access keys, endpoint URLs, Google Cloud Storage project IDs, local filesystem paths. |
| SMTP server addresses, credentials, sender addresses, template IDs, delivery rate limits. | |
| Search | Search engine endpoints, API keys, index names, reindex schedules. |
| Integrations | Third-party service API keys, webhook URLs, callback endpoints, partner credentials. |
| AI and Agents | Model provider API keys, model selection preferences, token limits, agent behavior settings. |
| Analytics | Data warehouse connection strings, retention periods, sampling rates, collector endpoints. |
How Configuration Connects to Other Systems
Configuration values are not static files — they are a live part of the platform's runtime. Multiple systems read configuration values as they operate:
- Scripts. Scripts running in the platform's sandboxed environment can read configuration values through the script API context. This lets scripts access API keys, endpoint URLs, and other settings without hardcoding them into the script source.
- AI agents. Agent workflows read configuration to determine which AI models to use, what API keys to authenticate with, and how to behave in specific contexts.
- Platform services. Core services — authentication, content processing, email delivery, analytics ingestion — read their operational parameters from configuration at startup and can detect changes at runtime.
- Client applications. Public configuration values can be read by client-side applications to control features, display settings, and behavior without requiring a redeployment of the client code.
This centralized configuration model means that changing a setting in one place updates the behavior across all systems that read it. There is no need to update multiple config files across multiple services.