diff --git a/docs/documentation/platform/event-subscriptions.mdx b/docs/documentation/platform/event-subscriptions.mdx
index cefef6824..1d36e5aa2 100644
--- a/docs/documentation/platform/event-subscriptions.mdx
+++ b/docs/documentation/platform/event-subscriptions.mdx
@@ -5,75 +5,143 @@ description: "Subscribe to events in Infisical for real-time updates"
---
- **Note:** Event Subscriptions is a paid feature. - **Infisical Cloud users:** Event Subscriptions is
- available under the **Enterprise Tier**. - **Self-Hosted Infisical:** Please
- contact [sales@infisical.com](mailto:sales@infisical.com) to purchase an
- enterprise license.
+ **Note:** Event Subscriptions is a paid feature.
+ - **Infisical Cloud users:** Event Subscriptions is available under the **Enterprise Tier**.
+ - **Self-Hosted Infisical:** Please contact [sales@infisical.com](mailto:sales@infisical.com) to purchase an enterprise license.
+Event Subscriptions in Infisical allow you to receive real-time notifications when specific actions occur within your account or organization. These notifications include changes to secrets, users, teams, and other important resources.
-Event Subscriptions in Infisical allow you to receive real-time notifications when specific actions occur within your account or organization. These notifications can include changes to secrets, users, teams, and other important resources.
+## How It Works
-You can currently subscribe to notifications for the following event types:
+Event Subscriptions enable real-time communication and state synchronization across multiple Infisical server instances through a distributed messaging architecture. The system leverages Redis as the central messaging backbone, utilizing Redis Pub/Sub to orchestrate event distribution in a fan-out pattern across all connected services. All server instances subscribe to a shared Redis topic named `infisical::core-servers`, ensuring consistent event delivery throughout the system.
-### Supported Event Types
+Event messages are structured according to the [CloudEvents specification](https://github.com/cloudevents/spec), providing a standardized format for cross-service communication. For client-side delivery, the system employs Server-Sent Events (SSE) streams, which offer efficient unidirectional communication without requiring specialized client libraries. This lightweight approach ensures seamless real-time updates while maintaining broad compatibility across different client environments.
-- `secret:created`: Triggered when a secret is created.
-- `secret:updated`: Triggered when a secret is updated.
-- `secret:deleted`: Triggered when a secret is deleted.
+
+ Event Subscriptions are designed for real-time communication and do not include persistence or replay capabilities—events are delivered once and are not stored for future retrieval.
+
+## Supported Resources
+
+You can currently subscribe to notifications for the following resources and event types:
+
+- **Secrets**
+ - `secret:created`: Triggered when a secret is created
+ - `secret:updated`: Triggered when a secret is updated
+ - `secret:deleted`: Triggered when a secret is deleted
## Permissions Setup
-In order to receive events on a supported resource, the identity is required to have a Subscribe permission on that resource. Follow these steps to set up the necessary permissions:
+To receive events on a supported resource, the identity must have `Subscribe` action permission on that resource.
+
+Follow these steps to set up the necessary permissions:
-
- 
- On your project page, open Project Settings from the sidebar.
- In the Project name section, click Copy Project ID to copy your Project ID, or extract it from the URL:
- `https://app.infisical.com/project//settings`
-
+
+ 
+
+ On your project page, open **Project Settings** from the sidebar.
+
+ In the Project name section, click **Copy Project ID** to copy your Project ID, or extract it from the URL:
+ `https://app.infisical.com/project//settings`
+
-
-   Navigate to{" "}
- Access Management, then select Project Roles
- .
-
+
+ 
+ 
+
+ Navigate to **Access Management**, then select **Project Roles**.
+
-
-  You can either edit
- an existing role or create a new role for event subscriptions.
-
+
+ 
+
+ You can either edit an existing role or create a new role for event subscriptions.
+
-
-  Select the specific
- resources that the role should have access to.
-
- 
-
+
+ 
+
+ Select the specific resources that the role should have access to.
+
+ 
+
-
- 
- Ensure the Subscribe action is selected for the relevant resources and events.
-
-
- By default, the role will have access to all events for the selected resources in this project.
- If needed, you can add filters to limit the scope of accessible events.
- 
-
-
-
+
+ 
+
+ Ensure the **Subscribe** action is selected for the relevant resources and events.
+
+
+
+ By default, the role will have access to all events for the selected resources in this project. If needed, you can add filters to limit the scope of accessible events.
+
+ 
+
+
+
-## Usage
+## Getting Started
-For integration and implementation details, please refer to our [API Reference](/api-reference/endpoints/events).
+Currently, events are only available via [API](/api-reference/endpoints/events) but will soon be available in our SDKs, Kubernetes Operator, and more.
----
+### API Authentication
-**Note:** Only users or roles with appropriate permissions can manage or subscribe to events.
+
+
+ 
+
+ Navigate to the **Organization Access Management** tab under Project access control settings.
+
+ 
+
+ Select or create an identity you want to create the token for.
+
-Availability: Event Subscriptions are not available on the Free
-plan.
+
+ 
+
+ Select a project and the role you previously configured in the [permissions setup](#permissions-setup) section.
+
+ 
+
+
+
+ 
+ 
+
+
+
+ 
+ 
+ 
+
+ Enter a descriptive name and click **Create**.
+
+ 
+
+ Click to copy the generated token and save it for later use.
+
+
+
+### API Usage
+
+#### Creating a Subscription
+
+
+
+**Request Parameters:**
+- `projectId`: Project whose events you want to subscribe to
+- `register`: List of event filters
+ - `conditions`: Conditions to filter events on
+ - `environmentSlug`: Project environment
+ - `secretPath`: Path of the secrets
+ - `recursive`: If `true`, gets events from all nested paths under `secretPath`
+
+
+
+The subscribe endpoint responds with a `text/event-stream` content type to initiate SSE streaming.
+
+For more specific details, please refer to our [API Reference](/api-reference/endpoints/events).
\ No newline at end of file
diff --git a/docs/images/platform/events/add-auth-method-form.png b/docs/images/platform/events/add-auth-method-form.png
new file mode 100644
index 000000000..ba181ff48
Binary files /dev/null and b/docs/images/platform/events/add-auth-method-form.png differ
diff --git a/docs/images/platform/events/add-auth-method.png b/docs/images/platform/events/add-auth-method.png
new file mode 100644
index 000000000..583f13d09
Binary files /dev/null and b/docs/images/platform/events/add-auth-method.png differ
diff --git a/docs/images/platform/events/copy-generated-token.png b/docs/images/platform/events/copy-generated-token.png
new file mode 100644
index 000000000..1fb061017
Binary files /dev/null and b/docs/images/platform/events/copy-generated-token.png differ
diff --git a/docs/images/platform/events/generate-auth-token-add.png b/docs/images/platform/events/generate-auth-token-add.png
new file mode 100644
index 000000000..2057e2509
Binary files /dev/null and b/docs/images/platform/events/generate-auth-token-add.png differ
diff --git a/docs/images/platform/events/generate-auth-token-create.png b/docs/images/platform/events/generate-auth-token-create.png
new file mode 100644
index 000000000..9bccbb16f
Binary files /dev/null and b/docs/images/platform/events/generate-auth-token-create.png differ
diff --git a/docs/images/platform/events/generate-auth-token.png b/docs/images/platform/events/generate-auth-token.png
new file mode 100644
index 000000000..40d6336a6
Binary files /dev/null and b/docs/images/platform/events/generate-auth-token.png differ
diff --git a/docs/images/platform/events/identity-add-project.png b/docs/images/platform/events/identity-add-project.png
new file mode 100644
index 000000000..5fdaa488e
Binary files /dev/null and b/docs/images/platform/events/identity-add-project.png differ
diff --git a/docs/images/platform/events/identity-add-role.png b/docs/images/platform/events/identity-add-role.png
new file mode 100644
index 000000000..c20296cf8
Binary files /dev/null and b/docs/images/platform/events/identity-add-role.png differ
diff --git a/docs/images/platform/events/identity-selector.png b/docs/images/platform/events/identity-selector.png
new file mode 100644
index 000000000..2aaf7e56b
Binary files /dev/null and b/docs/images/platform/events/identity-selector.png differ
diff --git a/docs/images/platform/events/org-access-control.png b/docs/images/platform/events/org-access-control.png
new file mode 100644
index 000000000..334d6dbc3
Binary files /dev/null and b/docs/images/platform/events/org-access-control.png differ
diff --git a/docs/images/platform/events/postman-sse-response.png b/docs/images/platform/events/postman-sse-response.png
new file mode 100644
index 000000000..fea1054b4
Binary files /dev/null and b/docs/images/platform/events/postman-sse-response.png differ
diff --git a/docs/images/platform/events/postman-subscribe.png b/docs/images/platform/events/postman-subscribe.png
new file mode 100644
index 000000000..308d257c0
Binary files /dev/null and b/docs/images/platform/events/postman-subscribe.png differ