diff --git a/api-ref/source/v2/parameters.yaml b/api-ref/source/v2/parameters.yaml
index 1337236d079..a91c42c5ef8 100644
--- a/api-ref/source/v2/parameters.yaml
+++ b/api-ref/source/v2/parameters.yaml
@@ -973,8 +973,13 @@ metadata_items:
   type: integer
 migration_policy:
   description: |
-    Specify if make migration when retyping volume, the value is 'on-demand'
-    or 'never'.
+    Specify if the volume should be migrated when it is re-typed.
+    Possible values are ``on-demand`` or ``never``. If not specified, the
+    default is ``never``.
+
+    .. note:: If the volume is attached to a server instance and will be
+      migrated, then by default policy only users with the administrative role
+      should attempt the retype operation.
   in: body
   required: false
   type: string
diff --git a/api-ref/source/v2/volumes-v2-volumes-actions.inc b/api-ref/source/v2/volumes-v2-volumes-actions.inc
index 9f70d9ff00a..000aa6161f8 100644
--- a/api-ref/source/v2/volumes-v2-volumes-actions.inc
+++ b/api-ref/source/v2/volumes-v2-volumes-actions.inc
@@ -315,6 +315,10 @@ Change type of existing volume. Specify the ``os-retype`` action in the request
 Change the volume type of existing volume, Cinder may migrate the volume to
 proper volume host according to the new volume type.
 
+Policy defaults enable only users with the administrative role or the owner of
+the volume to perform this operation. Cloud providers can change these
+permissions through the policy.json file.
+
 Normal response codes: 202
 
 
diff --git a/api-ref/source/v3/parameters.yaml b/api-ref/source/v3/parameters.yaml
index 5e48821a294..ed57a7c2caf 100644
--- a/api-ref/source/v3/parameters.yaml
+++ b/api-ref/source/v3/parameters.yaml
@@ -1187,8 +1187,13 @@ metadata_items:
   type: integer
 migration_policy:
   description: |
-    Specify if make migration when retyping volume, the value is 'on-demand'
-    or 'never'.
+    Specify if the volume should be migrated when it is re-typed.
+    Possible values are ``on-demand`` or ``never``. If not specified, the
+    default is ``never``.
+
+    .. note:: If the volume is attached to a server instance and will be
+      migrated, then by default policy only users with the administrative role
+      should attempt the retype operation.
   in: body
   required: false
   type: string
diff --git a/api-ref/source/v3/volumes-v3-volumes-actions.inc b/api-ref/source/v3/volumes-v3-volumes-actions.inc
index 681d47f50ab..cc69d258297 100644
--- a/api-ref/source/v3/volumes-v3-volumes-actions.inc
+++ b/api-ref/source/v3/volumes-v3-volumes-actions.inc
@@ -312,6 +312,10 @@ Change type of existing volume. Specify the ``os-retype`` action in the request
 Change the volume type of existing volume, Cinder may migrate the volume to
 proper volume host according to the new volume type.
 
+Policy defaults enable only users with the administrative role or the owner of
+the volume to perform this operation. Cloud providers can change these
+permissions through the policy.json file.
+
 Normal response codes: 202