diff --git a/docs/en/ml/limitations.asciidoc b/docs/en/ml/limitations.asciidoc
index 60fc7cafa5f..9a68ce026a2 100644
--- a/docs/en/ml/limitations.asciidoc
+++ b/docs/en/ml/limitations.asciidoc
@@ -157,3 +157,17 @@ poorer precision worthwhile. If you want to view or change the aggregations
 that are used in your job, refer to the `aggregations` property in your {dfeed}.
 
 For more information, see {ref}/ml-datafeed-resource.html[Datafeed Resources].
+
+[float]
+=== Security Integration
+
+When {security} is enabled, a {dfeed} stores the roles of the user who created
+or updated the {dfeed} **at that time**. This means that if those roles are
+updated then the {dfeed} will subsequently run with the new permissions associated
+with the roles. However, if the user's roles are adjusted after creating or
+updating the {dfeed} then the {dfeed} will continue to run with the permissions
+associated with the original roles.
+
+A way to update the roles stored within the {dfeed} without changing any other
+settings is to submit an empty JSON document (`{}`) to the
+{ref}/ml-update-datafeed.html[update {dfeed} API].
diff --git a/docs/en/rest-api/ml/preview-datafeed.asciidoc b/docs/en/rest-api/ml/preview-datafeed.asciidoc
index f3012170631..dfb402efa92 100644
--- a/docs/en/rest-api/ml/preview-datafeed.asciidoc
+++ b/docs/en/rest-api/ml/preview-datafeed.asciidoc
@@ -34,6 +34,17 @@ privileges to use this API. For more information, see
 //<<privileges-list-cluster>>.
 
 
+==== Security Integration
+
+When {security} is enabled, the {dfeed} query will be previewed using the
+credentials of the user calling the preview {dfeed} API.  When the {dfeed}
+is started it will run the query using the roles of the last user to
+create or update it.  If the two sets of roles differ then the preview may
+not accurately reflect what the {dfeed} will return when started.  To avoid
+such problems, the same user that creates/updates the {dfeed} should preview
+it to ensure it is returning the expected data.
+
+
 ==== Examples
 
 The following example obtains a preview of the `datafeed-farequote` {dfeed}:
diff --git a/docs/en/rest-api/ml/put-datafeed.asciidoc b/docs/en/rest-api/ml/put-datafeed.asciidoc
index 9ef0948a88b..2e367273690 100644
--- a/docs/en/rest-api/ml/put-datafeed.asciidoc
+++ b/docs/en/rest-api/ml/put-datafeed.asciidoc
@@ -87,6 +87,13 @@ For more information, see
 {xpack-ref}/security-privileges.html[Security Privileges].
 //<<privileges-list-cluster>>.
 
+
+==== Security Integration
+
+When {security} is enabled, your {dfeed} will remember which roles the user who
+created it had at the time of creation, and run the query using those same roles.
+
+
 ==== Examples
 
 The following example creates the `datafeed-total-requests` {dfeed}:
diff --git a/docs/en/rest-api/ml/start-datafeed.asciidoc b/docs/en/rest-api/ml/start-datafeed.asciidoc
index 147186fbfc1..801984deac0 100644
--- a/docs/en/rest-api/ml/start-datafeed.asciidoc
+++ b/docs/en/rest-api/ml/start-datafeed.asciidoc
@@ -81,6 +81,13 @@ For more information, see
 //<<privileges-list-cluster>>.
 
 
+==== Security Integration
+
+When {security} is enabled, your {dfeed} will remember which roles the last
+user to create or update it had at the time of creation/update, and run the query
+using those same roles.
+
+
 ==== Examples
 
 The following example starts the `datafeed-it-ops-kpi` {dfeed}:
diff --git a/docs/en/rest-api/ml/update-datafeed.asciidoc b/docs/en/rest-api/ml/update-datafeed.asciidoc
index a17b7892534..560f3c82ca2 100644
--- a/docs/en/rest-api/ml/update-datafeed.asciidoc
+++ b/docs/en/rest-api/ml/update-datafeed.asciidoc
@@ -82,6 +82,13 @@ For more information, see
 {xpack-ref}/security-privileges.html[Security Privileges].
 //<<privileges-list-cluster>>.
 
+
+==== Security Integration
+
+When {security} is enabled, your {dfeed} will remember which roles the user who
+updated it had at the time of update, and run the query using those same roles.
+
+
 ==== Examples
 
 The following example updates the query for the `datafeed-it-ops-kpi` {dfeed}