diff --git a/src/auth/types.rs b/src/auth/types.rs
index 19bd5f74..ad3184d7 100644
--- a/src/auth/types.rs
+++ b/src/auth/types.rs
@@ -400,6 +400,23 @@ mod tests {
         assert!(!ro.contains(&"logs_write_pipelines"));
     }
 
+    #[test]
+    fn test_default_scopes_excludes_workload_identity_federation() {
+        let scopes = default_scopes();
+        // workload_identity_federation_read/write are only ever granted to
+        // admins, so they're opt-in only (see 'pup cloud-auth' AUTHENTICATION
+        // doc) rather than requested by default.
+        assert!(!scopes.contains(&"workload_identity_federation_read"));
+        assert!(!scopes.contains(&"workload_identity_federation_write"));
+    }
+
+    #[test]
+    fn test_read_only_scopes_excludes_workload_identity_federation() {
+        let ro = read_only_scopes();
+        assert!(!ro.contains(&"workload_identity_federation_read"));
+        assert!(!ro.contains(&"workload_identity_federation_write"));
+    }
+
     #[test]
     fn test_read_only_scopes_subset_of_default() {
         let default: std::collections::HashSet<&str> = default_scopes().into_iter().collect();
diff --git a/src/main.rs b/src/main.rs
index cefe69b1..9e171c3d 100644
--- a/src/main.rs
+++ b/src/main.rs
@@ -7902,7 +7902,13 @@ enum IntegrationActions {
 #[derive(Subcommand)]
 enum IntegrationAwsActions {
     /// Manage AWS cloud authentication
-    #[command(name = "cloud-auth")]
+    ///
+    /// AUTHENTICATION:
+    ///   Requires OAuth2 (via 'pup auth login') or API + Application keys.
+    ///   OAuth2 requires the workload_identity_federation_read/write scopes,
+    ///   which are not requested by default -- opt in with:
+    ///     pup auth login --extra-scopes workload_identity_federation_read,workload_identity_federation_write
+    #[command(name = "cloud-auth", verbatim_doc_comment)]
     CloudAuth {
         #[command(subcommand)]
         action: CloudAuthActions,