Preferences: Add API validation and update documentation (#116045)

pkg/services/preference/prefapi/api.go

@@ -20,6 +20,10 @@ func UpdatePreferencesFor(ctx context.Context,
 		return response.Error(http.StatusBadRequest, "Invalid theme", nil)
 	}
 
+	if !pref.IsValidTimezone(dtoCmd.Timezone) {
+		return response.Error(http.StatusBadRequest, "Invalid timezone. Must be a valid IANA timezone (e.g., America/New_York), 'utc', 'browser', or empty string", nil)
+	}
+
 	// convert dashboard UID to ID in order to store internally if it exists in the query, otherwise take the id from query
 	// nolint:staticcheck
 	dashboardID := dtoCmd.HomeDashboardID

pkg/services/preference/timezone.go

@@ -0,0 +1,21 @@
+package pref
+
+import (
+	"time"
+)
+
+// IsValidTimezone checks if the timezone string is valid.
+// It accepts:
+// - "" - uses default
+// - "utc"
+// - "browser"
+// - Any valid IANA timezone (e.g., "America/New_York", "Europe/London")
+func IsValidTimezone(timezone string) bool {
+	if timezone == "" || timezone == "utc" || timezone == "browser" {
+		return true
+	}
+
+	// try to load as IANA timezone
+	_, err := time.LoadLocation(timezone)
+	return err == nil
+}

pkg/services/preference/timezone_test.go

@@ -0,0 +1,38 @@
+package pref
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+)
+
+func TestIsValidTimezone(t *testing.T) {
+	tests := []struct {
+		timezone string
+		valid    bool
+	}{
+		{
+			timezone: "utc",
+			valid:    true,
+		},
+		{
+			timezone: "browser",
+			valid:    true,
+		},
+		{
+			timezone: "Europe/London",
+			valid:    true,
+		},
+		{
+			timezone: "invalid",
+			valid:    false,
+		},
+		{
+			timezone: "",
+			valid:    true,
+		},
+	}
+	for _, test := range tests {
+		assert.Equal(t, test.valid, IsValidTimezone(test.timezone))
+	}
+}