Configuration

The Java SDK can be configured programmatically or through Spring Boot properties.

Spring Boot Configuration

Use the Spring provider registration, then configure via application.yml or application.properties:

YAML

toggly:
  # Required: Your application key from Toggly dashboard
  app-key: ${TOGGLY_APP_KEY}

  # Environment name (default: Production)
  environment: Production

  # Base URL for definitions API (default: https://definitions.toggly.io)
  base-url: https://definitions.toggly.io

  # Refresh interval in seconds (default: 30, 0 disables polling)
  refresh-interval-seconds: 30

  # Default state for undefined features (default: false)
  default-feature-state: false

  # Enable/disable Toggly integration (default: true)
  enabled: true

  # Per-feature default values
  feature-defaults:
    my-feature: true
    beta-feature: false

Properties

toggly.app-key=${TOGGLY_APP_KEY}
toggly.environment=Production
toggly.base-url=https://definitions.toggly.io
toggly.refresh-interval-seconds=30
toggly.default-feature-state=false
toggly.enabled=true
toggly.feature-defaults.my-feature=true

Signed definitions and live updates

Spring Boot properties do not currently bind useSignedDefinitions or enableLiveUpdates. Builder defaults apply when you provide a custom TogglyConfig bean (enableLiveUpdates=true, useSignedDefinitions=false). See Signed definitions and Live updates.

Programmatic Configuration

Use the builder pattern for programmatic configuration:

TogglyConfig config = TogglyConfig.builder()
    .appKey("your-app-key")
    .environment("Production")
    .baseUrl("https://definitions.toggly.io")
    .refreshIntervalSeconds(30)
    .defaultFeatureState(false)
    .useSignedDefinitions(true)
    .enableLiveUpdates(true)
    .featureDefault("my-feature", true)
    .featureDefault("beta-feature", false)
    .build();

try (TogglyClient client = new TogglyClient(config)) {
    client.refresh(); // Attempt the initial download.
    boolean enabled = client.isEnabled("my-feature");
}

Configuration Options

Option	Type	Default	Description
appKey	String	(required)	Your application key from Toggly dashboard
environment	String	Production	Environment name
baseUrl	String	https://definitions.toggly.io	Base URL for definitions API
refreshIntervalSeconds	long	180 (builder) / 30 (Spring props)	How often to refresh definitions (0 disables)
defaultFeatureState	boolean	false	Default state for unknown features
defaultIdentity	String	null	Default user identity for evaluations
featureDefaults	Map	{}	Per-feature default values
useSignedDefinitions	boolean	false	Verify ES256 signed definitions
enableLiveUpdates	boolean	true	WebSocket live updates
allowedKeyIds	Set<String>	empty	Allowed signing key IDs (empty = all)
onError	BiConsumer	null	Callback for refresh / signature failures

Signed definitions

See Signed definitions for JWKS + ES256 verification end-to-end. Persist exact signedDefsJson bytes — details in Caching and Server-side reliability.

Live updates (WebSockets)

See Live updates. Protocol: WebSocket sync.

Environment Variables

Your application reads environment variables explicitly. The core builder does not read these names automatically:

export TOGGLY_APP_KEY=your-app-key
export TOGGLY_ENVIRONMENT=Production

In Spring Boot, reference them in your configuration:

toggly:
  app-key: ${TOGGLY_APP_KEY}
  environment: ${TOGGLY_ENVIRONMENT:Production}

Use System.getenv("TOGGLY_APP_KEY") with the core builder. The native Servlet listener has a different mapping: toggly.appKey becomes TOGGLY_APPKEY, and literal ${...} values in web.xml are not expanded by the SDK. The Servlet setup shows an explicit override.

Initial state and errors

Construction does not guarantee a downloaded snapshot. Call refresh() at startup to attempt a fetch; an evaluation against an empty HTTP snapshot can also fetch synchronously. Configure onError to observe network/signature failures. The built-in HTTP provider retains the last good definitions on failure; before any successful download, configured defaults apply. Neither refresh() returning nor refreshAsync() completing proves that new definitions arrived.

For a multi-user server, omit defaultIdentity and pass a request context with its own identity. Supplying an identity-less context together with a configured default identity rebuilds the context with groups/traits only: claims, request and entity fields are lost. See Evaluation for request assembly.

Custom Snapshot Provider

You can provide a custom snapshot provider for special use cases:

Use the complete in-memory example for a deterministic provider. When you pass a provider into new TogglyClient(config, provider), the application owns that provider. Close the client first, then the provider (or let Spring destroy both beans). A client-created HTTP provider is closed by the client. Cache wrappers close their delegates; assign one owner to the outer wrapper.

Custom Evaluator Registry

Register custom filter evaluators:

EvaluatorRegistry registry = new EvaluatorRegistry();

// Register a custom evaluator
registry.register("MyCustomFilter", (filter, featureKey, context) -> {
    String value = filter.getStringParameter("value");
    return "expected".equals(value);
});

try (TogglyClient client = new TogglyClient(config, null, registry)) {
    boolean enabled = client.isEnabled("my-feature");
}

Disabling Auto-Refresh

Set refreshIntervalSeconds to 0 to disable polling. This does not disable WebSocket updates; also set .enableLiveUpdates(false) in a custom config bean if you need only manual refreshes:

toggly:
  refresh-interval-seconds: 0

Then manually refresh when needed:

// Synchronous refresh attempt
client.refresh();

// Asynchronous refresh attempt
client.refreshAsync().thenRun(() -> {
    System.out.println("Refresh attempt completed");
});

Multiple Environments

For applications that need to switch environments:

@Configuration
@Profile("staging")
public class StagingConfig {
    @Bean
    public TogglyConfig togglyConfig() {
        return TogglyConfig.builder()
            .appKey("staging-app-key")
            .environment("Staging")
            .build();
    }
}

@Configuration
@Profile("production")
public class ProductionConfig {
    @Bean
    public TogglyConfig togglyConfig() {
        return TogglyConfig.builder()
            .appKey("prod-app-key")
            .environment("Production")
            .build();
    }
}