diff --git a/api-ref/source/v3/parameters.yaml b/api-ref/source/v3/parameters.yaml
index 4b2352f870..789eb1aff7 100644
--- a/api-ref/source/v3/parameters.yaml
+++ b/api-ref/source/v3/parameters.yaml
@@ -1977,6 +1977,25 @@ user_object:
   in: body
   required: true
   type: object
+user_options_request_body:
+  description: |
+    The resource options for the user. Available resource options are
+    ``ignore_change_password_upon_first_use``, ``ignore_password_expiry``,
+    ``ignore_lockout_failure_attempts``, ``lock_password``,
+    ``multi_factor_auth_enabled``, and ``multi_factor_auth_rules``.
+  in: body
+  required: false
+  type: object
+user_options_response_body:
+  description: |
+    The resource options for the user. Only present in the response if set on
+    the user entity. Available resource options are
+    ``ignore_change_password_upon_first_use``, ``ignore_password_expiry``,
+    ``ignore_lockout_failure_attempts``, ``lock_password``,
+    ``multi_factor_auth_enabled``, and ``multi_factor_auth_rules``.
+  in: body
+  required: false
+  type: object
 user_password_update_body:
   description: |
     The new password for the user.
diff --git a/api-ref/source/v3/samples/admin/user-create-request.json b/api-ref/source/v3/samples/admin/user-create-request.json
index ecd7caeebc..f04ed72e78 100644
--- a/api-ref/source/v3/samples/admin/user-create-request.json
+++ b/api-ref/source/v3/samples/admin/user-create-request.json
@@ -6,6 +6,9 @@
         "name": "James Doe",
         "password": "secretsecret",
         "description": "James Doe user",
-        "email": "jdoe@example.com"
+        "email": "jdoe@example.com",
+        "options": {
+            "ignore_password_expiry": true
+        }
     }
 }
diff --git a/api-ref/source/v3/samples/admin/user-create-response.json b/api-ref/source/v3/samples/admin/user-create-response.json
index a56aaf2f9d..a66346df2d 100644
--- a/api-ref/source/v3/samples/admin/user-create-response.json
+++ b/api-ref/source/v3/samples/admin/user-create-response.json
@@ -10,6 +10,9 @@
             "self": "https://example.com/identity/v3/users/ff4e51"
         },
         "name": "James Doe",
+        "options": {
+            "ignore_password_expiry": true
+        },
         "password_expires_at": "2016-11-06T15:32:17.000000"
     }
 }
diff --git a/api-ref/source/v3/samples/admin/user-update-request.json b/api-ref/source/v3/samples/admin/user-update-request.json
index ebed994d7a..a464db8cde 100644
--- a/api-ref/source/v3/samples/admin/user-update-request.json
+++ b/api-ref/source/v3/samples/admin/user-update-request.json
@@ -1,6 +1,9 @@
 {
     "user": {
         "default_project_id": "263fd9",
-        "enabled": true
+        "enabled": true,
+        "options": {
+            "ignore_lockout_failure_attempts": true
+        }
     }
 }
diff --git a/api-ref/source/v3/samples/admin/user-update-response.json b/api-ref/source/v3/samples/admin/user-update-response.json
index 47e921c86d..350b2a4fec 100644
--- a/api-ref/source/v3/samples/admin/user-update-response.json
+++ b/api-ref/source/v3/samples/admin/user-update-response.json
@@ -8,6 +8,9 @@
             "self": "https://example.com/identity/v3/users/ff4e51"
         },
         "name": "jamesdoe",
+        "options": {
+            "ignore_lockout_failure_attempts": true
+        },
         "password_expires_at": "2016-11-06T15:32:17.000000"
     }
 }
diff --git a/api-ref/source/v3/users.inc b/api-ref/source/v3/users.inc
index 0dd9a9697f..aee2d33860 100644
--- a/api-ref/source/v3/users.inc
+++ b/api-ref/source/v3/users.inc
@@ -104,6 +104,7 @@ Parameters
    - name: user_name_create_request_body
    - password: password_request_body
    - extra: extra_request_body
+   - options: user_options_request_body
 
 Example
 ~~~~~~~
@@ -127,6 +128,7 @@ Parameters
    - links: links_user
    - name: user_name_response_body
    - password_expires_at: password_expires_at
+   - options: user_options_response_body
 
 Status Codes
 ~~~~~~~~~~~~
@@ -233,6 +235,7 @@ Parameters
    - enabled: enabled_user_update_body
    - name: user_name_update_body
    - password: user_update_password_body
+   - options: user_options_request_body
 
 Example
 ~~~~~~~
@@ -256,6 +259,7 @@ Parameters
    - links: links_user
    - name: user_name_response_body
    - password_expires_at: password_expires_at
+   - options: user_options_response_body
 
 Status Codes
 ~~~~~~~~~~~~
diff --git a/releasenotes/notes/bug-1792026-2de8345a89e2256b.yaml b/releasenotes/notes/bug-1792026-2de8345a89e2256b.yaml
new file mode 100644
index 0000000000..f1eb433367
--- /dev/null
+++ b/releasenotes/notes/bug-1792026-2de8345a89e2256b.yaml
@@ -0,0 +1,9 @@
+---
+fixes:
+  - |
+    [`bug 1792026 <https://bugs.launchpad.net/keystone/+bug/1792026>`_]
+    Formal documentation for user resource options has been added to the
+    administrator guide and the API reference. This documentation helps
+    describe how user options can improve user experience, namely for
+    deployments looking to offer flexibility around PCI-DSS security
+    requirements, among other things.