diff --git a/docs/resources/access_identity_provider.md b/docs/resources/access_identity_provider.md
index 1665150f55..cec84badcc 100644
--- a/docs/resources/access_identity_provider.md
+++ b/docs/resources/access_identity_provider.md
@@ -128,12 +128,12 @@ Read-Only:
 
 Optional:
 
-- `enabled` (Boolean)
-- `group_member_deprovision` (Boolean)
-- `identity_update_behavior` (String)
-- `seat_deprovision` (Boolean)
-- `secret` (String, Sensitive)
-- `user_deprovision` (Boolean)
+- `enabled` (Boolean) A flag to enable or disable SCIM for the identity provider.
+- `group_member_deprovision` (Boolean) Deprecated. Use `identity_update_behavior`.
+- `identity_update_behavior` (String) Indicates how a SCIM event updates a user identity used for policy evaluation. Use "automatic" to automatically update a user's identity and augment it with fields from the SCIM user resource. Use "reauth" to force re-authentication on group membership updates, user identity update will only occur after successful re-authentication. With "reauth" identities will not contain fields from the SCIM user resource. With "no_action" identities will not be changed by SCIM updates in any way and users will not be prompted to reauthenticate.
+- `seat_deprovision` (Boolean) A flag to remove a user's seat in Zero Trust when they have been deprovisioned in the Identity Provider.  This cannot be enabled unless user_deprovision is also enabled.
+- `secret` (String, Sensitive) A read-only token generated when the SCIM integration is enabled for the first time.  It is redacted on subsequent requests.  If you lose this you will need to refresh it token at /access/identity_providers/:idpID/refresh_scim_secret.
+- `user_deprovision` (Boolean) A flag to enable revoking a user's session in Access and Gateway when they have been deprovisioned in the Identity Provider.
 
 ## Import
 
diff --git a/docs/resources/access_policy.md b/docs/resources/access_policy.md
index 44ac5b241f..531387752f 100644
--- a/docs/resources/access_policy.md
+++ b/docs/resources/access_policy.md
@@ -245,6 +245,9 @@ Required:
 Required:
 
 - `usernames` (List of String) Contains the Unix usernames that may be used when connecting over SSH.
+
+Optional:
+
 - `allow_email_alias` (Boolean) Allows connecting to Unix username that matches the authenticating email prefix.
 
 
diff --git a/docs/resources/zero_trust_access_identity_provider.md b/docs/resources/zero_trust_access_identity_provider.md
index 53d328b43d..506ea1a68a 100644
--- a/docs/resources/zero_trust_access_identity_provider.md
+++ b/docs/resources/zero_trust_access_identity_provider.md
@@ -128,12 +128,12 @@ Read-Only:
 
 Optional:
 
-- `enabled` (Boolean)
-- `group_member_deprovision` (Boolean)
-- `identity_update_behavior` (String)
-- `seat_deprovision` (Boolean)
-- `secret` (String, Sensitive)
-- `user_deprovision` (Boolean)
+- `enabled` (Boolean) A flag to enable or disable SCIM for the identity provider.
+- `group_member_deprovision` (Boolean) Deprecated. Use `identity_update_behavior`.
+- `identity_update_behavior` (String) Indicates how a SCIM event updates a user identity used for policy evaluation. Use "automatic" to automatically update a user's identity and augment it with fields from the SCIM user resource. Use "reauth" to force re-authentication on group membership updates, user identity update will only occur after successful re-authentication. With "reauth" identities will not contain fields from the SCIM user resource. With "no_action" identities will not be changed by SCIM updates in any way and users will not be prompted to reauthenticate.
+- `seat_deprovision` (Boolean) A flag to remove a user's seat in Zero Trust when they have been deprovisioned in the Identity Provider.  This cannot be enabled unless user_deprovision is also enabled.
+- `secret` (String, Sensitive) A read-only token generated when the SCIM integration is enabled for the first time.  It is redacted on subsequent requests.  If you lose this you will need to refresh it token at /access/identity_providers/:idpID/refresh_scim_secret.
+- `user_deprovision` (Boolean) A flag to enable revoking a user's session in Access and Gateway when they have been deprovisioned in the Identity Provider.
 
 ## Import
 
diff --git a/docs/resources/zero_trust_access_policy.md b/docs/resources/zero_trust_access_policy.md
index 6b370b963a..a700d9074c 100644
--- a/docs/resources/zero_trust_access_policy.md
+++ b/docs/resources/zero_trust_access_policy.md
@@ -206,6 +206,9 @@ Required:
 Required:
 
 - `usernames` (List of String) Contains the Unix usernames that may be used when connecting over SSH.
+
+Optional:
+
 - `allow_email_alias` (Boolean) Allows connecting to Unix username that matches the authenticating email prefix.