diff --git a/docs/reference/concepts/01-evaluation-api.mdx b/docs/reference/concepts/01-evaluation-api.mdx
index edf78de8f..588e4f018 100644
--- a/docs/reference/concepts/01-evaluation-api.mdx
+++ b/docs/reference/concepts/01-evaluation-api.mdx
@@ -42,7 +42,7 @@ OpenFeature.setProvider(new YourProviderOfChoice());
```java
-import dev.openfeature.javasdk.OpenFeatureAPI;
+import dev.openfeature.sdk.OpenFeatureAPI;
OpenFeatureAPI api = OpenFeatureAPI.getInstance();
api.setProvider(new YourProviderOfChoice());
@@ -85,6 +85,11 @@ openfeature.api.set_provider(YourProviderOfChoice())
+Some providers need to establish connections, load flag data, or validate configuration before they can resolve flags accurately.
+If your SDK exposes a blocking or awaitable registration method, use it during startup when your application needs to avoid default values while the provider initializes.
+If you register the provider asynchronously, attach event handlers for [`PROVIDER_READY`](./events#provider_ready) and [`PROVIDER_ERROR`](./events#provider_error) so your application can react when initialization succeeds or fails.
+See [Events](./events#event-handlers) for language-specific handler examples.
+
## Creating a client
The OpenFeature client is a lightweight abstraction used to evaluate feature flags.
@@ -275,15 +280,15 @@ These return the value, as well as additional metadata about the flag evaluation
#### Evaluation Details Structure Fields
-| Field | Description |
-| ------------------------ | --------------------------------------------------------------------------------------------- |
-| flag key | the unique identifier for a feature flag |
-| value | the value returned from a flag evaluation |
-| reason (optional) | a string explaining why the flag value was returned |
-| variant (optional) | the variant associated with the return flag value |
-| flag metadata (optional) | a key-value structure which supports definition of arbitrary properties |
+| Field | Description |
+| ------------------------ | ---------------------------------------------------------------------------------------- |
+| flag key | the unique identifier for a feature flag |
+| value | the value returned from a flag evaluation |
+| reason (optional) | a string explaining why the flag value was returned |
+| variant (optional) | the variant associated with the return flag value |
+| flag metadata (optional) | a key-value structure which supports definition of arbitrary properties |
| error code (optional) | an [error code](/specification/types#error-code) that categorizes flag evaluation errors |
-| error message (optional) | a string detailing the error |
+| error message (optional) | a string detailing the error |
@@ -404,3 +409,39 @@ details = client.get_object_details("objectFlag", {});
+
+## API Shutdown
+
+The OpenFeature API can shut down all registered providers so they can release connections, background workers, file watchers, or other resources.
+Call this from your application shutdown path after you stop evaluating flags.
+The method name varies by SDK; use the shutdown or close function documented by the SDK you are using.
+
+
+
+
+```ts
+import { OpenFeature } from '@openfeature/server-sdk';
+
+await OpenFeature.close();
+```
+
+
+
+
+```java
+import dev.openfeature.sdk.OpenFeatureAPI;
+
+OpenFeatureAPI.getInstance().shutdown();
+```
+
+
+
+
+```python
+from openfeature import api
+
+api.shutdown()
+```
+
+
+
diff --git a/docs/reference/concepts/02-provider.mdx b/docs/reference/concepts/02-provider.mdx
index e05e92292..d1808f5a8 100644
--- a/docs/reference/concepts/02-provider.mdx
+++ b/docs/reference/concepts/02-provider.mdx
@@ -117,6 +117,71 @@ const multiProvider = new MultiProvider(
await OpenFeature.setProviderAndWait(multiProvider);
```
+### Provider lifecycle
+
+Providers can implement lifecycle methods that the SDK calls when the provider is registered and when the API shuts down.
+Use initialization to open network connections, load remote flag state, validate configuration, or start background workers that are required before evaluations should use the provider.
+Use shutdown to release those same resources during application shutdown.
+The exact method names vary by SDK, but they map to the same lifecycle: initialize when the provider is set, and clean up when the [Evaluation API is shut down](./evaluation-api#api-shutdown).
+When your application needs to wait until initialization completes, use the SDK's waitable provider registration method when available.
+If the provider is registered without waiting, application authors can use [`PROVIDER_READY`](./events#provider_ready) and [`PROVIDER_ERROR`](./events#provider_error) handlers to react to provider startup events.
+
+
+
+
+```ts
+import { EvaluationContext, Provider } from '@openfeature/server-sdk';
+
+class MyFeatureProvider implements Provider {
+ readonly metadata = {
+ name: 'My Feature Provider',
+ } as const;
+
+ readonly runsOn = 'server';
+
+ async initialize(context?: EvaluationContext): Promise {
+ // Open connections, validate configuration, or preload flag state here.
+ }
+
+ async onClose(): Promise {
+ // Close connections or stop background workers here.
+ }
+
+ // Implement the required resolve*Evaluation methods shown in the provider examples below.
+}
+```
+
+
+
+
+```java
+import dev.openfeature.sdk.EvaluationContext;
+import dev.openfeature.sdk.FeatureProvider;
+import dev.openfeature.sdk.Metadata;
+
+public class MyProvider implements FeatureProvider {
+ @Override
+ public Metadata getMetadata() {
+ return () -> "My Provider";
+ }
+
+ @Override
+ public void initialize(EvaluationContext evaluationContext) throws Exception {
+ // Open connections, validate configuration, or preload flag state here.
+ }
+
+ @Override
+ public void shutdown() {
+ // Close connections or stop background workers here.
+ }
+
+ // Implement the required evaluation methods shown in the provider examples below.
+}
+```
+
+
+
+
### Examples
#### Dynamic Context Implementations (Server-side SDKs)