Initialize and run multiple SDK instances in one application, with each instance having its own SDK key and environment. The instances are fully isolated. Use multiple SDK keys when you need to read or compare flags across environments without redeploying, to support multi-tenant routing, or to combine server-side and client-side evaluations in one application.
When to use multiple SDK keys
Use multiple SDK keys when your application needs to evaluate flags across more than one environment or context, for example:
-
Multi‑tenant isolation: Route evaluations per tenant or customer to different environments.
-
Regional isolation: Evaluate against region‑specific environments.
-
Cross-team feature sets: Load flags and targeting rules from multiple projects so teams retain ownership and RBAC while the application evaluates both.
Review prerequisites for implementing multiple SDK keys
Review these requirements before implementing multiple SDK keys. They apply to all supported platforms.
-
SDK v6.x or later for your platform.
-
One SDK key per application-environment you plan to use.
-
The flags you plan to evaluate exist in each application and environment being queried.
-
Network access to the CloudBees platform endpoints from your runtime.
Understand how multiple SDK keys operate in your application
The SDK models multiple keys, isolates data and operations, supports runtime context switching, and lets each instance register multiple containers with namespaces.
-
One instance per key: Each SDK instance is initialized with a single SDK key and evaluates flags only for that environment.
-
Isolation: Caches, network connections and streams, fetch and polling, callbacks and listeners, and telemetry are independent per instance.
-
Context switching: You choose the instance per request, user, or tenant; that instance auto-fetches and applies flag updates.
-
Lifecycle: Initialize, fetch and stream, and shut down each instance separately.
-
Backward compatibility: The legacy singleton and static API still works; you can mix it with instance-based clients to adopt multi-key incrementally to register, fetch, stream, and evaluate on the same target, and prefer instance-scoped APIs when using multiple keys.
Set up multiple SDK keys
These steps provide an overview of the process and are SDK‑agnostic. For concrete code, refer to these examples.
-
Retrieve the SDK keys for the environments you’ll use.
-
Initialize a separate SDK instance for each key.
-
Decide how to route requests to instances; for example, by tenant, region, or environment selector.
-
Perform register, fetch, and stream setup on each instance as required by your SDK.
-
Evaluate flags using the selected instance; pass a consistent user/context object for accurate targeting.
-
Tag logs or metrics for each instance, and shut down instances you no longer need.
Recommended practices
Use these practices to maintain clear isolation between instances, consistent evaluations, and reliable operations when using multiple SDK keys.
- Instance Management
-
Store instance references for reuse. Use consistent naming conventions for SDK keys.
- Flag Naming
-
Use prefixes to distinguish flags from different configurations. For example:
prod_enableFeaturevsstaging_enableFeature - Custom Properties
-
Set custom properties on the specific instance. Avoid using static custom property methods with multiple SDK keys.
- Error Handling
-
Set up configuration fetched handlers for each instance. Monitor for network errors per instance.
Troubleshoot common issues
Use this list to quickly diagnose and resolve common multiple SDK issues.
- Wrong environment evaluated
-
Ensure you select the intended SDK instance before evaluation.
- No updates applied
-
Confirm register, fetch, or streaming is configured for that specific instance.
- Callbacks not firing
-
Attach listeners to the same instance that performs fetch/streaming.
- Unexpected differences
-
Compare flag definitions, targeting rules, and salts across environments.
- High network activity
-
Reduce the number of active instances or adjust polling or stream settings.