diff --git a/API_DESIGN.md b/API_DESIGN.md
index c13e1c64d3a..cc89d1c6c65 100644
--- a/API_DESIGN.md
+++ b/API_DESIGN.md
@@ -53,7 +53,7 @@ Please check out the structure Buf style guide for more information about the fo
 As a rule of thumb, redundant API methods are deprecated.
 
 - The proto option `grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation.deprecated` MUST be set to true.
-- One or more links to recommended replacement methods MUST be added to the deprecation message as a proto comment above the rpc spec.
+- One or more links to recommended replacement methods CAN be added to the deprecation message as a proto comment above the rpc spec.
 - Guidance for switching to the recommended methods for common use cases SHOULD be added as a proto comment above the rpc spec.
 
 #### Example
diff --git a/internal/api/grpc/settings/v2/server.go b/internal/api/grpc/settings/v2/server.go
index 3f7c2a02ecc..8fba2345773 100644
--- a/internal/api/grpc/settings/v2/server.go
+++ b/internal/api/grpc/settings/v2/server.go
@@ -25,8 +25,6 @@ type Server struct {
 	assetsAPIDomain func(context.Context) string
 }
 
-type Config struct{}
-
 func CreateServer(
 	command *command.Commands,
 	query *query.Queries,
diff --git a/internal/api/grpc/settings/v2/settings_converter.go b/internal/api/grpc/settings/v2/settings_converter.go
index b1329a5973f..1dec0186578 100644
--- a/internal/api/grpc/settings/v2/settings_converter.go
+++ b/internal/api/grpc/settings/v2/settings_converter.go
@@ -25,6 +25,7 @@ func loginSettingsToPb(current *query.LoginPolicy) *settings.LoginSettings {
 
 	return &settings.LoginSettings{
 		AllowUsernamePassword:      current.AllowUsernamePassword,
+		AllowLocalAuthentication:   current.AllowUsernamePassword,
 		AllowRegister:              current.AllowRegister,
 		AllowExternalIdp:           current.AllowExternalIDPs,
 		ForceMfa:                   current.ForceMFA,
@@ -68,7 +69,7 @@ func passkeysTypeToPb(passwordlessType domain.PasswordlessType) settings.Passkey
 func secondFactorTypeToPb(secondFactorType domain.SecondFactorType) settings.SecondFactorType {
 	switch secondFactorType {
 	case domain.SecondFactorTypeTOTP:
-		return settings.SecondFactorType_SECOND_FACTOR_TYPE_OTP
+		return settings.SecondFactorType_SECOND_FACTOR_TYPE_TOTP
 	case domain.SecondFactorTypeU2F:
 		return settings.SecondFactorType_SECOND_FACTOR_TYPE_U2F
 	case domain.SecondFactorTypeOTPEmail:
diff --git a/internal/api/grpc/settings/v2/settings_converter_test.go b/internal/api/grpc/settings/v2/settings_converter_test.go
index 937daf6712a..f365c0ea237 100644
--- a/internal/api/grpc/settings/v2/settings_converter_test.go
+++ b/internal/api/grpc/settings/v2/settings_converter_test.go
@@ -55,6 +55,7 @@ func Test_loginSettingsToPb(t *testing.T) {
 
 	want := &settings.LoginSettings{
 		AllowUsernamePassword:      true,
+		AllowLocalAuthentication:   true,
 		AllowRegister:              true,
 		AllowExternalIdp:           true,
 		ForceMfa:                   true,
@@ -153,8 +154,13 @@ func Test_secondFactorTypeToPb(t *testing.T) {
 		want settings.SecondFactorType
 	}{
 		{
+			// making sure it doesn't break existing mappings
 			args: args{domain.SecondFactorTypeTOTP},
-			want: settings.SecondFactorType_SECOND_FACTOR_TYPE_OTP,
+			want: settings.SecondFactorType_SECOND_FACTOR_TYPE_OTP, //nolint:staticcheck
+		},
+		{
+			args: args{domain.SecondFactorTypeTOTP},
+			want: settings.SecondFactorType_SECOND_FACTOR_TYPE_TOTP,
 		},
 		{
 			args: args{domain.SecondFactorTypeU2F},
diff --git a/proto/zitadel/settings/v2/branding_settings.proto b/proto/zitadel/settings/v2/branding_settings.proto
index 84c4ecd755d..6f2aeb16295 100644
--- a/proto/zitadel/settings/v2/branding_settings.proto
+++ b/proto/zitadel/settings/v2/branding_settings.proto
@@ -8,78 +8,73 @@ import "protoc-gen-openapiv2/options/annotations.proto";
 import "zitadel/settings/v2/settings.proto";
 
 message BrandingSettings {
+  // Theme used for light mode.
   Theme light_theme = 1;
+
+  // Theme used for dark mode.
   Theme dark_theme = 2;
+
+  // The url where the font is served.
   string font_url = 3 [
     (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
-      description: "url to the font used";
       example: "\"https://acme.com/assets/v1/165617850692654601/policy/label/font-180950243237405441\"";
     }
   ];
-  // hides the org suffix on the login form if the scope \"urn:zitadel:iam:org:domain:primary:{domainname}\" is set
-  bool hide_login_name_suffix = 4 [
-    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
-      description: "hides the org suffix on the login form if the scope \"urn:zitadel:iam:org:domain:primary:{domainname}\" is set";
-    }
-  ];
-  bool disable_watermark = 5 [
-    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
-      description: "boolean to disable the watermark";
-    }
-  ];
-  // resource_owner_type returns if the setting is managed on the organization or on the instance
-  ResourceOwnerType resource_owner_type = 6 [
-    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
-      description: "resource_owner_type returns if the setting is managed on the organization or on the instance";
-    }
-  ];
-  ThemeMode theme_mode = 7 [
-    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
-      description: "states whether both or only dark or light theme will be used";
-    }
-  ];
+
+  // If enabled, the organization suffix will be hidden on the login form if the scope \"urn:zitadel:iam:org:domain:primary:{domainname}\" is used.
+  bool hide_login_name_suffix = 4;
+
+  // If enabled, the Zitadel logo will not be displayed on the login screen.
+  bool disable_watermark = 5;
+
+  // ResourceOwnerType returns if the setting is managed on the organization explicitly or
+  // fell back on the instance settings.
+  ResourceOwnerType resource_owner_type = 6;
+
+  // States which themes will be used. If auto is selected, the theme will be changed based on the users system preferences.
+  // You can also choose to only allow dark or light theme.
+  ThemeMode theme_mode = 7;
 }
 
 message Theme {
-  // hex value for primary color
+  // The hex value for primary color.
   string primary_color = 1 [
     (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
-      description: "hex value for primary color";
       example: "\"#5469d4\"";
     }
   ];
-  // hex value for background color
+
+  // The hex value for background color.
   string background_color = 2 [
     (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
-      description: "hex value for background color";
       example: "\"#FAFAFA\"";
     }
   ];
-  // hex value for warning color
+
+  // The hex value for warning color.
   string warn_color = 3 [
     (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
-      description: "hex value for warn color";
       example: "\"#CD3D56\"";
     }
   ];
-  // hex value for font color
+
+  // The value for font color.
   string font_color = 4 [
     (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
-      description: "hex value for font color";
       example: "\"#000000\"";
     }
   ];
-  // url where the logo is served
+
+  // The URL where the logo is served.
   string logo_url = 5 [
     (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
-      description: "url to the logo";
       example: "\"https://acme.com/assets/v1/165617850692654601/policy/label/logo-180950416321494657\"";
     }
   ];
-  // url where the icon is served
+
+  // The URL where the icon is served.
   string icon_url = 6 [
     (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
-      description: "url to the icon";
       example: "\"https://acme.com/assets/v1/165617850692654601/policy/label/icon-180950498874178817\"";
     }
   ];
diff --git a/proto/zitadel/settings/v2/domain_settings.proto b/proto/zitadel/settings/v2/domain_settings.proto
index 0649e65ba17..f57be7deb5d 100644
--- a/proto/zitadel/settings/v2/domain_settings.proto
+++ b/proto/zitadel/settings/v2/domain_settings.proto
@@ -8,26 +8,19 @@ import "protoc-gen-openapiv2/options/annotations.proto";
 import "zitadel/settings/v2/settings.proto";
 
 message DomainSettings {
-  bool login_name_includes_domain = 1 [
-    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
-      description: "the username has to end with the domain of its organization"
-    }
-  ];
-  bool require_org_domain_verification = 2 [
-    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
-      description: "defines if organization domains should be verified upon creation, otherwise will be created already verified"
-    }
-  ];
-  bool smtp_sender_address_matches_instance_domain = 3 [
-    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
-      description: "defines if the SMTP sender address domain should match an existing domain on the instance"
-    }
-  ];
-  // resource_owner_type returns if the setting is managed on the organization or on the instance
-  ResourceOwnerType resource_owner_type = 6 [
-    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
-      description: "resource_owner_type returns if the setting is managed on the organization or on the instance";
-    }
-  ];
+  // If enabled, the login name will automatically be suffixed with the domain of the organization.
+  // This ensures that the login name is unique across the instance.
+  bool login_name_includes_domain = 1;
+
+  // If enabled, organization domains must be verified (through an DNS or HTTP challenge) upon creation.
+  // If disabled, organization domains will be created as already verified automatically.
+  bool require_org_domain_verification = 2;
+
+  // If enabled, the SMTP sender address domain must match custom domain on the instance.
+  bool smtp_sender_address_matches_instance_domain = 3;
+
+  // ResourceOwnerType returns if the setting is managed on the organization explicitly or
+  // fell back on the instance settings.
+  ResourceOwnerType resource_owner_type = 6;
 }
 
diff --git a/proto/zitadel/settings/v2/legal_settings.proto b/proto/zitadel/settings/v2/legal_settings.proto
index acd34e6ccb3..f4c2e20cf88 100644
--- a/proto/zitadel/settings/v2/legal_settings.proto
+++ b/proto/zitadel/settings/v2/legal_settings.proto
@@ -9,50 +9,57 @@ import "zitadel/settings/v2/settings.proto";
 import "validate/validate.proto";
 
 message LegalAndSupportSettings {
+  // Link to the Terms of Service. Can be a relative or absolute URL.
   string tos_link = 1 [
     (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
       example: "\"https://zitadel.com/docs/legal/terms-of-service\"";
     }
   ];
+
+  // Link to the Privacy Policy. Can be a relative or absolute URL.
   string privacy_policy_link = 2 [
     (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
       example: "\"https://zitadel.com/docs/legal/privacy-policy\"";
     }
   ];
+
+  // Link to a help page. Can be a relative or absolute URL.
   string help_link = 3 [
     (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
       example: "\"https://zitadel.com/docs/manuals/introduction\"";
     }
   ];
+
+  // Email address for support issues.
   string support_email = 4 [
     (validate.rules).string = {ignore_empty: true, max_len: 320, email: true},
     (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
       example: "\"support-email@test.com\"";
-      description: "help / support email address."
-    }
-  ];
-  // resource_owner_type returns if the setting is managed on the organization or on the instance
-  ResourceOwnerType resource_owner_type = 5 [
-    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
-      description: "resource_owner_type returns if the setting is managed on the organization or on the instance";
     }
   ];
+
+  // ResourceOwnerType returns if the setting is managed on the organization explicitly or
+  // fell back on the instance settings.
+  ResourceOwnerType resource_owner_type = 5;
+
+  // Link to documentation to be shown in the console.
   string docs_link = 6 [
     (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
-        description: "Link to documentation to be shown in the console.";
         example: "\"https://zitadel.com/docs\"";
     }
-];
-string custom_link = 7 [
+  ];
+
+  // Link to an external resource that will be available to users in the console.
+  string custom_link = 7 [
     (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
-        description: "Link to an external resource that will be available to users in the console.";
         example: "\"https://external.link\"";
     }
-];
-string custom_link_text = 8 [
+  ];
+
+  // The button text that would be shown in console pointing to custom link.
+  string custom_link_text = 8 [
     (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
-        description: "The button text that would be shown in console pointing to custom link.";
         example: "\"External\"";
     }
-];
+  ];
 }
diff --git a/proto/zitadel/settings/v2/lockout_settings.proto b/proto/zitadel/settings/v2/lockout_settings.proto
index f4fefc27094..be88cb489f5 100644
--- a/proto/zitadel/settings/v2/lockout_settings.proto
+++ b/proto/zitadel/settings/v2/lockout_settings.proto
@@ -8,21 +8,24 @@ import "protoc-gen-openapiv2/options/annotations.proto";
 import "zitadel/settings/v2/settings.proto";
 
 message LockoutSettings {
+  // The amount of failed password attempts before the account gets locked.
+  // Attempts are reset as soon as the password is entered correctly or the password is reset.
+  // If set to 0 the account will never be locked.
   uint64 max_password_attempts = 1 [
     (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
-      description: "Maximum password check attempts before the account gets locked. Attempts are reset as soon as the password is entered correctly or the password is reset. If set to 0 the account will never be locked."
       example: "\"10\""
     }
   ];
-  // resource_owner_type returns if the settings is managed on the organization or on the instance
-  ResourceOwnerType resource_owner_type = 2 [
-    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
-      description: "resource_owner_type returns if the settings is managed on the organization or on the instance";
-    }
-  ];
+
+  // ResourceOwnerType returns if the settings is managed on the organization explicitly or
+  // fell back on the instance settings.
+  ResourceOwnerType resource_owner_type = 2;
+
+  // THe amount of failed OTP (TOTP, SMS, Email) attempts before the account gets locked.
+  // Attempts are reset as soon as the OTP is entered correctly.
+  // If set to 0 the account will never be locked.
   uint64 max_otp_attempts = 3 [
     (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
-      description: "Maximum failed attempts for a single OTP type (TOTP, SMS, Email) before the account gets locked. Attempts are reset as soon as the OTP is entered correctly. If set to 0 the account will never be locked."
       example: "\"10\""
     }
   ];
diff --git a/proto/zitadel/settings/v2/login_settings.proto b/proto/zitadel/settings/v2/login_settings.proto
index 2b5194f0b59..35c8e019e06 100644
--- a/proto/zitadel/settings/v2/login_settings.proto
+++ b/proto/zitadel/settings/v2/login_settings.proto
@@ -10,112 +10,144 @@ import "zitadel/idp/v2/idp.proto";
 import "google/protobuf/duration.proto";
 
 message LoginSettings {
+  // If enabled, users can log in locally with their username and passkeys or password.
+  // Disabling this option will require users to log in with an external identity provider.
+  // Be sure to allow at least one external identity provider if this option is disabled.
+  // Deprecated: check allow_local_authentication instead.
   bool allow_username_password = 1 [
-    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
-      description: "defines if a user is allowed to log in with username and password";
-    }
-  ];
-  bool allow_register = 2 [
-    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
-      description: "defines if a person is allowed to register a user on this organization";
-    }
-  ];
-  bool allow_external_idp = 3 [
-    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
-      description: "defines if a user is allowed to add a defined identity provider. E.g. Google auth";
-    }
-  ];
-  bool force_mfa = 4 [
-    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
-      description: "defines if a user MUST use a multi-factor to log in";
-    }
-  ];
-  PasskeysType passkeys_type = 5 [
-    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
-      description: "defines if passkeys are allowed for users"
-    }
-  ];
-  bool hide_password_reset = 6 [
-    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
-      description: "defines if password reset link should be shown in the login screen"
-    }
-  ];
-  bool ignore_unknown_usernames = 7 [
-    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
-      description: "defines if unknown username on login screen directly returns an error or always displays the password screen"
-    }
+    deprecated = true
   ];
+
+  // If enabled, users can log in locally with their username and passkeys or password.
+  // Disabling this option will require users to log in with an external identity provider.
+  // Be sure to allow at least one external identity provider if this option is disabled.
+  bool allow_local_authentication = 20;
+
+  // If enabled, users can register a local account by themself.
+  // This option does not effect external identity providers.
+  // Each identity provider can be configured to allow or disallow registration.
+  bool allow_register = 2;
+
+  // If enabled, users will generally be allowed to use an external identity provider to log in.
+  // Be sure to allow at least one external identity provider if this option is enabled.
+  bool allow_external_idp = 3;
+
+  // If enabled, users will be forced to use a multi-factor to log in.
+  // This also applies to federated logins through an external identity provider.
+  // Users will be required to set up a second factor if they have not done so already.
+  bool force_mfa = 4;
+
+  // Defines the usage of passkeys for users.
+  // PASSKEYS_TYPE_NOT_ALLOWED: Users are not allowed to use passkeys.
+  // PASSKEYS_TYPE_ALLOWED: Users are allowed to use passkeys.
+  // There will be additional options in the future.
+  // If passkeys are allowed, users can choose to use passkeys or password for local authentication.
+  // A verified passkey authentication will not require a second factor, if force_mfa is enabled.
+  PasskeysType passkeys_type = 5;
+
+  // If enabled, the password reset link will be hidden on the login screen.
+  bool hide_password_reset = 6;
+
+  // If enabled, an unknown username on the login screen will not return an error directly,
+  // but will always display the password screen.
+  // This prevents user enumeration attacks.
+  bool ignore_unknown_usernames = 7;
+
+  // Defines where the user will be redirected to if the login is started without app context (e.g. from mail).
   string default_redirect_uri = 8 [
     (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
-      description: "defines where the user will be redirected to if the login is started without app context (e.g. from mail)";
       example: "\"https://acme.com/ui/console\"";
     }
   ];
+
+  // The duration a password check is valid.
+  // After this time has passed, the user will be required to re-validate their
+  // password on the next action that requires authentication.
+  // Note that this does not enforce a logout or session expiration.
   google.protobuf.Duration password_check_lifetime = 9 [
     (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
-      description: "Defines after how much time the user has to re-authenticate with the password.";
       example: "\"864000s\"";
     }
   ];
+
+  // The duration a login through an external identity provider is valid.
+  // After this time has passed, the user will be required to re-authenticate with the
+  // external identity provider on the next action that requires authentication.
+  // Note that this does not enforce a logout or session expiration.
   google.protobuf.Duration external_login_check_lifetime = 10 [
     (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
-      description: "Defines after how much time the user has to re-authenticate with an external provider.";
       example: "\"864000s\"";
     }
   ];
+
+  // Defines after how much time the mfa prompt will be shown again.
   google.protobuf.Duration mfa_init_skip_lifetime = 11 [
     (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
-      description: "Defines after how much time the mfa prompt will be shown again.";
       example: "\"2592000s\"";
     }
   ];
+
+  // The duration a second factor check is valid.
+  // After this time has passed, the user will be required to re-validate their
+  // second factor on the next action that requires authentication.
+  // Note that this does not enforce a logout or session expiration.
   google.protobuf.Duration second_factor_check_lifetime = 12 [
     (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
-      description: "Defines after how long the second factor check is valid.";
       example: "\"64800s\"";
     }
   ];
+
+  // The duration a multi-factor check is valid.
+  // After this time has passed, the user will be required to re-validate their
+  // multi-factor on the next action that requires authentication.
+  // Note that this does not enforce a logout or session expiration.
   google.protobuf.Duration multi_factor_check_lifetime = 13 [
     (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
-      description: "Defines how long the multi-factor check is valid.";
       example: "\"43200s\"";
     }
   ];
+
+  // The list of allowed second factors.
   repeated SecondFactorType second_factors = 14;
+
+  // The list of allowed multi factors.
   repeated MultiFactorType multi_factors = 15;
-  // If set to true, the suffix (@domain.com) of an unknown username input on the login screen will be matched against the org domains and will redirect to the registration of that organization on success.
-  bool allow_domain_discovery = 16 [
-    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
-      description: "If set to true, the suffix (@domain.com) of an unknown username input on the login screen will be matched against the org domains and will redirect to the registration of that organization on success."
-    }
-  ];
-  bool disable_login_with_email = 17 [
-    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
-      description: "defines if the user can additionally (to the login name) be identified by their verified email address"
-    }
-  ];
-  bool disable_login_with_phone = 18 [
-    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
-      description: "defines if the user can additionally (to the login name) be identified by their verified phone number"
-    }
-  ];
-  // resource_owner_type returns if the settings is managed on the organization or on the instance
-  ResourceOwnerType resource_owner_type = 19 [
-    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
-      description: "resource_owner_type returns if the settings is managed on the organization or on the instance";
-    }
-  ];
-  bool force_mfa_local_only = 22 [
-    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
-      description: "if activated, only local authenticated users are forced to use MFA. Authentication through IDPs won't prompt a MFA step in the login."
-    }
-  ];
+
+  // Allow discovery of the organization and its authentication option by domain.
+  // If set to true, the suffix (@domain.com) of an unknown username input on the login screen
+  // will be matched against the organization domains and will redirect to the registration of that organization on success.
+  // The registration can either be locally (requires allow_register to be true) or through an external identity provider.
+  // In case only one identity provider is configured for the organization, the user will be redirected directly to the identity provider.
+  bool allow_domain_discovery = 16;
+
+  // By default, users can login with their verified email address additionally to their login name.
+  // Setting this to true disables the email login.
+  // Note: If the email is set as the login name, this setting has no effect.
+  bool disable_login_with_email = 17 ;
+
+  // By default, users can login with their verified phone number additionally to their login name.
+  // Setting this to true disables the phone number login.
+  // Note: If the phone number is set as the login name, this setting has no effect.
+  bool disable_login_with_phone = 18;
+
+  // ResourceOwnerType returns if the settings is managed on the organization explicitly or
+  // fell back on the instance settings.
+  ResourceOwnerType resource_owner_type = 19;
+
+  // If enabled, users will be forced to use a multi-factor to log in if they authenticated locally.
+  // This does not apply to federated logins through an external identity provider.
+  // Users will be required to set up a second factor if they have not done so already.
+  // If both force_mfa and force_mfa_local_only are enabled, force_mfa takes precedence and
+  // all logins will require a second factor.
+  bool force_mfa_local_only = 22;
 }
 
 enum SecondFactorType {
+  option allow_alias = true;
   SECOND_FACTOR_TYPE_UNSPECIFIED = 0;
-  // This is the type for TOTP
+  // Deprecated: use SECOND_FACTOR_TYPE_TOTP instead.
   SECOND_FACTOR_TYPE_OTP = 1;
+  SECOND_FACTOR_TYPE_TOTP = 1;
   SECOND_FACTOR_TYPE_U2F = 2;
   SECOND_FACTOR_TYPE_OTP_EMAIL = 3;
   SECOND_FACTOR_TYPE_OTP_SMS = 4;
diff --git a/proto/zitadel/settings/v2/password_settings.proto b/proto/zitadel/settings/v2/password_settings.proto
index d75ccec39eb..ef9057f3e3b 100644
--- a/proto/zitadel/settings/v2/password_settings.proto
+++ b/proto/zitadel/settings/v2/password_settings.proto
@@ -8,38 +8,28 @@ import "protoc-gen-openapiv2/options/annotations.proto";
 import "zitadel/settings/v2/settings.proto";
 
 message PasswordComplexitySettings {
+  // The minimum length a password must have.
   uint64 min_length = 1 [
     (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
-      description: "Defines the minimum length of a password.";
       example: "\"8\""
     }
   ];
-  bool requires_uppercase = 2 [
-    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
-      description: "defines if the password MUST contain an upper case letter"
-    }
-  ];
-  bool requires_lowercase = 3 [
-    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
-      description: "defines if the password MUST contain a lowercase letter"
-    }
-  ];
-  bool requires_number = 4 [
-    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
-      description: "defines if the password MUST contain a number"
-    }
-  ];
-  bool requires_symbol = 5 [
-    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
-      description: "defines if the password MUST contain a symbol. E.g. \"$\""
-    }
-  ];
-  // resource_owner_type returns if the settings is managed on the organization or on the instance
-  ResourceOwnerType resource_owner_type = 6 [
-    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
-      description: "resource_owner_type returns if the settings is managed on the organization or on the instance";
-    }
-  ];
+
+  // Defines if the password MUST contain an upper case letter.
+  bool requires_uppercase = 2;
+
+  // Defines if the password MUST contain a lowercase letter.
+  bool requires_lowercase = 3;
+
+  // Defines if the password MUST contain a number.
+  bool requires_number = 4;
+
+  // Defines if the password MUST contain a symbol or special character. E.g. "$"
+  bool requires_symbol = 5;
+
+  // ResourceOwnerType returns if the settings is managed on the organization explicitly or
+  // fell back on the instance settings.
+  ResourceOwnerType resource_owner_type = 6;
 }
 
 message PasswordExpirySettings {
@@ -49,12 +39,15 @@ message PasswordExpirySettings {
       example: "\"365\""
     }
   ];
+
   // Amount of days after which the user should be notified of the upcoming expiry. ZITADEL will not notify the user.
   uint64 expire_warn_days = 2 [
     (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
       example: "\"10\""
     }
   ];
-  // resource_owner_type returns if the settings is managed on the organization or on the instance
+
+  // ResourceOwnerType returns if the settings is managed on the organization explicitly or
+  // fail back on the instance settings.
   ResourceOwnerType resource_owner_type = 3;
 }
diff --git a/proto/zitadel/settings/v2/security_settings.proto b/proto/zitadel/settings/v2/security_settings.proto
index 1045022baba..18444d44749 100644
--- a/proto/zitadel/settings/v2/security_settings.proto
+++ b/proto/zitadel/settings/v2/security_settings.proto
@@ -7,25 +7,19 @@ option go_package = "github.com/zitadel/zitadel/pkg/grpc/settings/v2;settings";
 import "protoc-gen-openapiv2/options/annotations.proto";
 
 message SecuritySettings {
+  // EmbeddedIframeSettings defines if the login UI can be embedded in an iframe
+  // and which origins are allowed to do so.
   EmbeddedIframeSettings embedded_iframe = 1;
-  bool enable_impersonation = 2 [
-    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
-      description: "default language for the current context"
-      example: "\"en\""
-    }
-  ];
+
+  // If enabled, users are allowed to impersonate other users.
+  // The impersonator needs the appropriate `*_IMPERSONATOR` roles assigned as well".
+  bool enable_impersonation = 2;
 }
 
 message EmbeddedIframeSettings{
-  bool enabled = 1 [
-    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
-      description: "states if iframe embedding is enabled or disabled"
-    }
-  ];
-  repeated string allowed_origins = 2 [
-    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
-      description: "origins allowed loading ZITADEL in an iframe if enabled."
-      example: "[\"foo.bar.com\", \"localhost:8080\"]"
-    }
-  ];
+  // Enabled states if iframe embedding is enabled or disabled.
+  bool enabled = 1;
+
+  // AllowedOrigins defines which origins are allowed to embed ZITADEL in an iframe.
+  repeated string allowed_origins = 2;
 }
diff --git a/proto/zitadel/settings/v2/settings_service.proto b/proto/zitadel/settings/v2/settings_service.proto
index ea3e2c3653f..2182a289e6a 100644
--- a/proto/zitadel/settings/v2/settings_service.proto
+++ b/proto/zitadel/settings/v2/settings_service.proto
@@ -112,7 +112,12 @@ option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_swagger) = {
 
 service SettingsService {
 
-  // Get basic information over the instance
+  // Get General Settings
+  //
+  // Get basic information of the instance like the default organization, default language and supported languages.
+  //
+  // Required permissions:
+  //   - `policy.read`
   rpc GetGeneralSettings (GetGeneralSettingsRequest) returns (GetGeneralSettingsResponse) {
     option (google.api.http) = {
       get: "/v2/settings"
@@ -125,8 +130,6 @@ service SettingsService {
     };
 
     option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
-      summary: "Get basic information over the instance";
-      description: "Return the basic information of the instance for the requested context"
       responses: {
         key: "200"
         value: {
@@ -136,7 +139,14 @@ service SettingsService {
     };
   }
 
-  // Get the login settings
+  // Get Login Settings
+  //
+  // Get the login settings for the requested context.
+  // This can be the instance or an organization. In case of an organization,
+  // the returned settings will fall back to the instance settings if not explicitly set on the organization.
+  //
+  // Required permissions:
+  //   - `policy.read`
   rpc GetLoginSettings (GetLoginSettingsRequest) returns (GetLoginSettingsResponse) {
     option (google.api.http) = {
       get: "/v2/settings/login"
@@ -149,8 +159,6 @@ service SettingsService {
     };
 
     option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
-      summary: "Get the login settings";
-      description: "Return the settings for the requested context"
       responses: {
         key: "200"
         value: {
@@ -160,7 +168,21 @@ service SettingsService {
     };
   }
 
-  // Get the current active identity providers
+  // Get Active Identity Providers
+  //
+  // Get the current active identity providers for the requested context.
+  // This can be the instance or an organization. In case of an organization,
+  // the returned identity providers will fall back to the active instance identity providers
+  // if not explicitly set on the organization.
+  //
+  // Optionally, filter the identity providers by their allowed actions:
+  //   - creation_allowed: only return identity providers that are allowed for user creation
+  //   - linking_allowed: only return identity providers that are allowed for linking to existing users
+  //   - auto_creation: only return identity providers that are allowed for automatic user creation
+  //   - auto_linking: only return identity providers that are allowed for automatic linking to existing users
+  //
+  // Required permissions:
+  //   - `policy.read`
   rpc GetActiveIdentityProviders (GetActiveIdentityProvidersRequest) returns (GetActiveIdentityProvidersResponse) {
     option (google.api.http) = {
       get: "/v2/settings/login/idps"
@@ -173,8 +195,6 @@ service SettingsService {
     };
 
     option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
-      summary: "Get the current active identity providers";
-      description: "Return the current active identity providers for the requested context"
       responses: {
         key: "200"
         value: {
@@ -184,7 +204,14 @@ service SettingsService {
     };
   }
 
-  // Get the password complexity settings
+  // Get Password Complexity Settings
+  //
+  // Get the password complexity settings for the requested context.
+  // This can be the instance or an organization. In case of an organization,
+  // the returned settings will fall back to the instance settings if not explicitly set on the organization.
+  //
+  // Required permissions:
+  //   - `policy.read`
   rpc GetPasswordComplexitySettings (GetPasswordComplexitySettingsRequest) returns (GetPasswordComplexitySettingsResponse) {
     option (google.api.http) = {
       get: "/v2/settings/password/complexity"
@@ -197,8 +224,6 @@ service SettingsService {
     };
 
     option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
-      summary: "Get the password complexity settings";
-      description: "Return the password complexity settings for the requested context"
       responses: {
         key: "200"
         value: {
@@ -208,7 +233,14 @@ service SettingsService {
     };
   }
 
-  // Get the password expiry settings
+  // Get Password Expiry Settings
+  //
+  // Get the password expiry settings for the requested context.
+  // This can be the instance or an organization. In case of an organization,
+  // the returned settings will fall back to the instance settings if not explicitly set on the organization.
+  //
+  // Required permissions:
+  //   - `policy.read`
   rpc GetPasswordExpirySettings (GetPasswordExpirySettingsRequest) returns (GetPasswordExpirySettingsResponse) {
     option (google.api.http) = {
       get: "/v2/settings/password/expiry"
@@ -221,8 +253,6 @@ service SettingsService {
     };
 
     option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
-      summary: "Get the password expiry settings";
-      description: "Return the password expiry settings for the requested context"
       responses: {
         key: "200"
         value: {
@@ -232,7 +262,14 @@ service SettingsService {
     };
   }
 
-  // Get the current active branding settings
+  // Get Branding Settings
+  //
+  // Get the current active branding settings for the requested context.
+  // This can be the instance or an organization. In case of an organization,
+  // the returned settings will fall back to the instance settings if not explicitly set on the organization.
+  //
+  // Required permissions:
+  //   - `policy.read`
   rpc GetBrandingSettings (GetBrandingSettingsRequest) returns (GetBrandingSettingsResponse) {
     option (google.api.http) = {
       get: "/v2/settings/branding"
@@ -245,8 +282,6 @@ service SettingsService {
     };
 
     option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
-      summary: "Get the current active branding settings";
-      description: "Return the current active branding settings for the requested context"
       responses: {
         key: "200"
         value: {
@@ -256,7 +291,14 @@ service SettingsService {
     };
   }
 
-  // Get the domain settings
+  // Get Domain Settings
+  //
+  // Get the domain settings for the requested context.
+  // This can be the instance or an organization. In case of an organization,
+  // the returned settings will fall back to the instance settings if not explicitly set on the organization.
+  //
+  // Required permissions:
+  //   - `policy.read`
   rpc GetDomainSettings (GetDomainSettingsRequest) returns (GetDomainSettingsResponse) {
     option (google.api.http) = {
       get: "/v2/settings/domain"
@@ -269,8 +311,6 @@ service SettingsService {
     };
 
     option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
-      summary: "Get the domain settings";
-      description: "Return the domain settings for the requested context"
       responses: {
         key: "200"
         value: {
@@ -280,7 +320,14 @@ service SettingsService {
     };
   }
 
-  // Get the legal and support settings
+  // Get Legal and Support Settings
+  //
+  // Get the legal and support settings for the requested context.
+  // This can be the instance or an organization. In case of an organization,
+  // the returned settings will fall back to the instance settings if not explicitly set on the organization.
+  //
+  // Required permissions:
+  //   - `policy.read`
   rpc GetLegalAndSupportSettings (GetLegalAndSupportSettingsRequest) returns (GetLegalAndSupportSettingsResponse) {
     option (google.api.http) = {
       get: "/v2/settings/legal_support"
@@ -293,8 +340,6 @@ service SettingsService {
     };
 
     option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
-      summary: "Get the legal and support settings";
-      description: "Return the legal settings for the requested context"
       responses: {
         key: "200"
         value: {
@@ -304,7 +349,16 @@ service SettingsService {
     };
   }
 
-  // Get the lockout settings
+  // Get Lockout Settings
+  //
+  // Get the lockout settings for the requested context.
+  // This can be the instance or an organization. In case of an organization,
+  // the returned settings will fall back to the instance settings if not explicitly set on the organization.
+  //
+  // Lockout settings define how many failed attempts are allowed before a user is locked out.
+  //
+  // Required permissions:
+  //   - `policy.read`
   rpc GetLockoutSettings (GetLockoutSettingsRequest) returns (GetLockoutSettingsResponse) {
     option (google.api.http) = {
       get: "/v2/settings/lockout"
@@ -317,8 +371,6 @@ service SettingsService {
     };
 
     option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
-      summary: "Get the lockout settings";
-      description: "Return the lockout settings for the requested context, which define when a user will be locked"
       responses: {
         key: "200"
         value: {
@@ -328,7 +380,13 @@ service SettingsService {
     };
   }
 
-  // Get the security settings
+  // Get Security Settings
+  //
+  // Get the security settings of the ZITADEL instance.
+  // Security settings include settings like enabling impersonation and embedded iframe settings.
+  //
+  // Required permissions:
+  //   - `iam.policy.read`
   rpc GetSecuritySettings(GetSecuritySettingsRequest) returns (GetSecuritySettingsResponse) {
     option (google.api.http) = {
       get: "/v2/settings/security";
@@ -339,15 +397,14 @@ service SettingsService {
         permission: "iam.policy.read"
       }
     };
-
-    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
-      tags: "Settings";
-      summary: "Get Security Settings";
-      description: "Returns the security settings of the ZITADEL instance."
-    };
   }
 
-  // Set the security settings
+  // Set Security Settings
+  //
+  // Set the security settings of the instance.
+  //
+  // Required permissions:
+  //   - `iam.policy.write`
   rpc SetSecuritySettings(SetSecuritySettingsRequest) returns (SetSecuritySettingsResponse) {
     option (google.api.http) = {
       put: "/v2/policies/security";
@@ -359,12 +416,6 @@ service SettingsService {
         permission: "iam.policy.write"
       }
     };
-
-    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
-      tags: "Settings";
-      summary: "Set Security Settings";
-      description: "Set the security settings of the ZITADEL instance."
-    };
   }
 
   // Get Hosted Login Translation
@@ -432,6 +483,10 @@ service SettingsService {
 }
 
 message GetLoginSettingsRequest {
+  // Specify the context for which the login settings should be returned.
+  // This can be the instance or an organization.
+  // In case of an organization, the returned settings will fall back to the instance settings
+  // if not explicitly set on the organization.
   zitadel.object.v2.RequestContext ctx = 1;
 }
 
@@ -441,6 +496,10 @@ message GetLoginSettingsResponse {
 }
 
 message GetPasswordComplexitySettingsRequest {
+  // Specify the context for which the password complexity settings should be returned.
+  // This can be the instance or an organization.
+  // In case of an organization, the returned settings will fall back to the instance settings
+  // if not explicitly set on the organization.
   zitadel.object.v2.RequestContext ctx = 1;
 }
 
@@ -450,6 +509,10 @@ message GetPasswordComplexitySettingsResponse {
 }
 
 message GetPasswordExpirySettingsRequest {
+  // Specify the context for which the password expiry settings should be returned.
+  // This can be the instance or an organization.
+  // In case of an organization, the returned settings will fall back to the instance settings
+  // if not explicitly set on the organization.
   zitadel.object.v2.RequestContext ctx = 1;
 }
 
@@ -459,6 +522,10 @@ message GetPasswordExpirySettingsResponse {
 }
 
 message GetBrandingSettingsRequest {
+  // Specify the context for which the branding settings should be returned.
+  // This can be the instance or an organization.
+  // In case of an organization, the returned settings will fall back to the instance settings
+  // if not explicitly set on the organization.
   zitadel.object.v2.RequestContext ctx = 1;
 }
 
@@ -468,6 +535,10 @@ message GetBrandingSettingsResponse {
 }
 
 message GetDomainSettingsRequest {
+  // Specify the context for which the domain settings should be returned.
+  // This can be the instance or an organization.
+  // In case of an organization, the returned settings will fall back to the instance settings
+  // if not explicitly set on the organization.
   zitadel.object.v2.RequestContext ctx = 1;
 }
 
@@ -477,6 +548,10 @@ message GetDomainSettingsResponse {
 }
 
 message GetLegalAndSupportSettingsRequest {
+  // Specify the context for which the legal and support settings should be returned.
+  // This can be the instance or an organization.
+  // In case of an organization, the returned settings will fall back to the instance settings
+  // if not explicitly set on the organization.
   zitadel.object.v2.RequestContext ctx = 1;
 }
 
@@ -486,6 +561,10 @@ message GetLegalAndSupportSettingsResponse {
 }
 
 message GetLockoutSettingsRequest {
+  // Specify the context for which the lockout settings should be returned.
+  // This can be the instance or an organization.
+  // In case of an organization, the returned settings will fall back to the instance settings
+  // if not explicitly set on the organization.
   zitadel.object.v2.RequestContext ctx = 1;
 }
 
@@ -495,6 +574,10 @@ message GetLockoutSettingsResponse {
 }
 
 message GetActiveIdentityProvidersRequest {
+  // Specify the context for which the active identity providers should be returned.
+  // This can be the instance or an organization.
+  // In case of an organization, the returned providers will fall back to the instance providers
+  // if not explicitly set on the organization.
   zitadel.object.v2.RequestContext ctx = 1;
   optional bool creation_allowed = 2;
   optional bool linking_allowed = 3;
@@ -510,25 +593,32 @@ message GetActiveIdentityProvidersResponse {
 message GetGeneralSettingsRequest {}
 
 message GetGeneralSettingsResponse {
-  string default_org_id = 1 [
-    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
-      description: "default organization for the current context"
-    }
-  ];
+  // The unique identifier of the default organization.
+  // The default organization is used to assign new users to an organization if no other organization is specified.
+  // Deprecated: use default_organization_id instead.
+  string default_org_id = 1;
+
+  // The default language is use if no other language is specified or detected.
+  // The format is a BCP 47 language tag (e.g. "en", "de", "fr-CH").
   string default_language = 2 [
     (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
-      description: "default language for the current context"
       example: "\"en\""
     }
   ];
+
+  // The list of supported languages.
+  // The format is a BCP 47 language tag (e.g. "en", "de", "fr-CH").
   repeated string supported_languages = 3 [
     (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
       example: "[\"en\", \"de\", \"it\"]"
     }
   ];
+
+  // The unique identifier of the default organization.
+  // The default organization is used to assign new users to an organization if no other organization is specified.
+  string default_organization_id = 4;
 }
 
-// This is an empty request
 message GetSecuritySettingsRequest{}
 
 message GetSecuritySettingsResponse{
@@ -537,12 +627,13 @@ message GetSecuritySettingsResponse{
 }
 
 message SetSecuritySettingsRequest{
+  // EmbeddedIframeSettings defines if the login UI can be embedded in an iframe
+  // and which origins are allowed to do so.
   EmbeddedIframeSettings embedded_iframe = 1;
-  bool enable_impersonation = 2 [
-    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
-      description: "allows users to impersonate other users. The impersonator needs the appropriate `*_IMPERSONATOR` roles assigned as well"
-    }
-  ];
+
+  // If enabled, users are allowed to impersonate other users.
+  // The impersonator needs the appropriate `*_IMPERSONATOR` roles assigned as well".
+  bool enable_impersonation = 2;
 }
 
 message SetSecuritySettingsResponse{
@@ -550,12 +641,17 @@ message SetSecuritySettingsResponse{
 }
 
 message GetHostedLoginTranslationRequest {
+  // Specify the level from which the translation should be returned.
+  // If the requested level doesn't contain all translations, and ignore_inheritance is set to false
+  // a merging process fallbacks onto the higher levels ensuring all keys in the file have a translation.
   oneof level {
     bool system = 1 [(validate.rules).bool = {const: true}];
     bool instance = 2 [(validate.rules).bool = {const: true}];
     string organization_id = 3;
   }
 
+  // The locale of the translations to be returned.
+  // Needs to be a BCP 47 language tag (e.g. "en", "de", "fr-CH").
   string locale = 4 [
     (validate.rules).string = {min_len: 2},
     (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
@@ -579,20 +675,27 @@ message GetHostedLoginTranslationResponse {
     }
   ];
 
+  // Translations contains the translations in the requested language.
   google.protobuf.Struct translations = 2 [
     (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
       example: "{\"common\":{\"back\":\"Indietro\"},\"accounts\":{\"title\":\"Account\",\"description\":\"Seleziona l'account che desideri utilizzare.\",\"addAnother\":\"Aggiungi un altro account\",\"noResults\":\"Nessun account trovato\"}}";
-      description: "Translations contains the translations in the request language.";
     }
   ];
 }
 
 message SetHostedLoginTranslationRequest {
+  // Specify the level on which the translation should be set.
+  // Only instance or organization level is allowed.
+  // System level translations can't be modified.
+  // In case of organization level, the organization_id needs to be set.
+  // If a translation already exists on the specified level, it will be overwritten.
   oneof level {
     bool instance = 1 [(validate.rules).bool = {const: true}];
     string organization_id = 2;
   }
 
+  // The locale of the translations to be set.
+  // Needs to be a BCP 47 language tag (e.g. "en", "de", "fr-CH").
   string locale = 3 [
     (validate.rules).string = {min_len: 2},
     (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
@@ -601,10 +704,10 @@ message SetHostedLoginTranslationRequest {
     }
   ];
 
+  // Translations should contain the translations in the specified locale.
   google.protobuf.Struct translations = 4 [
     (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
       example: "{\"common\":{\"back\":\"Indietro\"},\"accounts\":{\"title\":\"Account\",\"description\":\"Seleziona l'account che desideri utilizzare.\",\"addAnother\":\"Aggiungi un altro account\",\"noResults\":\"Nessun account trovato\"}}";
-      description: "Translations should contain the translations in the specified locale.";
     }
   ];
 }
diff --git a/proto/zitadel/settings/v2beta/settings_service.proto b/proto/zitadel/settings/v2beta/settings_service.proto
index a1679b7cb7c..6f159f238d4 100644
--- a/proto/zitadel/settings/v2beta/settings_service.proto
+++ b/proto/zitadel/settings/v2beta/settings_service.proto
@@ -109,9 +109,12 @@ option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_swagger) = {
   }
 };
 
+// Deprecated: use settings service v2 instead. This service will be removed in the next major version of ZITADEL.
 service SettingsService {
 
   // Get basic information over the instance
+  //
+  // Deprecated: please move to the corresponding endpoint under settings service v2. This endpoint will be removed with the next major version of ZITADEL.
   rpc GetGeneralSettings (GetGeneralSettingsRequest) returns (GetGeneralSettingsResponse) {
     option (google.api.http) = {
       get: "/v2beta/settings"
@@ -124,6 +127,7 @@ service SettingsService {
     };
 
     option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
+      deprecated: true;
       summary: "Get basic information over the instance";
       description: "Return the basic information of the instance for the requested context"
       responses: {
@@ -136,6 +140,8 @@ service SettingsService {
   }
 
   // Get the login settings
+  //
+  // Deprecated: please move to the corresponding endpoint under settings service v2. This endpoint will be removed with the next major version of ZITADEL.
   rpc GetLoginSettings (GetLoginSettingsRequest) returns (GetLoginSettingsResponse) {
     option (google.api.http) = {
       get: "/v2beta/settings/login"
@@ -148,6 +154,7 @@ service SettingsService {
     };
 
     option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
+      deprecated: true;
       summary: "Get the login settings";
       description: "Return the settings for the requested context"
       responses: {
@@ -160,6 +167,8 @@ service SettingsService {
   }
 
   // Get the current active identity providers
+  //
+  // Deprecated: please move to the corresponding endpoint under settings service v2. This endpoint will be removed with the next major version of ZITADEL.
   rpc GetActiveIdentityProviders (GetActiveIdentityProvidersRequest) returns (GetActiveIdentityProvidersResponse) {
     option (google.api.http) = {
       get: "/v2beta/settings/login/idps"
@@ -172,6 +181,7 @@ service SettingsService {
     };
 
     option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
+      deprecated: true;
       summary: "Get the current active identity providers";
       description: "Return the current active identity providers for the requested context"
       responses: {
@@ -184,6 +194,8 @@ service SettingsService {
   }
 
   // Get the password complexity settings
+  //
+  // Deprecated: please move to the corresponding endpoint under settings service v2. This endpoint will be removed with the next major version of ZITADEL.
   rpc GetPasswordComplexitySettings (GetPasswordComplexitySettingsRequest) returns (GetPasswordComplexitySettingsResponse) {
     option (google.api.http) = {
       get: "/v2beta/settings/password/complexity"
@@ -196,6 +208,7 @@ service SettingsService {
     };
 
     option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
+      deprecated: true;
       summary: "Get the password complexity settings";
       description: "Return the password complexity settings for the requested context"
       responses: {
@@ -208,6 +221,8 @@ service SettingsService {
   }
 
   // Get the password expiry settings
+  //
+  // Deprecated: please move to the corresponding endpoint under settings service v2. This endpoint will be removed with the next major version of ZITADEL.
   rpc GetPasswordExpirySettings (GetPasswordExpirySettingsRequest) returns (GetPasswordExpirySettingsResponse) {
     option (google.api.http) = {
       get: "/v2beta/settings/password/expiry"
@@ -220,6 +235,7 @@ service SettingsService {
     };
 
     option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
+      deprecated: true;
       summary: "Get the password expiry settings";
       description: "Return the password expiry settings for the requested context"
       responses: {
@@ -232,6 +248,8 @@ service SettingsService {
   }
 
   // Get the current active branding settings
+  //
+  // Deprecated: please move to the corresponding endpoint under settings service v2. This endpoint will be removed with the next major version of ZITADEL.
   rpc GetBrandingSettings (GetBrandingSettingsRequest) returns (GetBrandingSettingsResponse) {
     option (google.api.http) = {
       get: "/v2beta/settings/branding"
@@ -244,6 +262,7 @@ service SettingsService {
     };
 
     option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
+      deprecated: true;
       summary: "Get the current active branding settings";
       description: "Return the current active branding settings for the requested context"
       responses: {
@@ -256,6 +275,8 @@ service SettingsService {
   }
 
   // Get the domain settings
+  //
+  // Deprecated: please move to the corresponding endpoint under settings service v2. This endpoint will be removed with the next major version of ZITADEL.
   rpc GetDomainSettings (GetDomainSettingsRequest) returns (GetDomainSettingsResponse) {
     option (google.api.http) = {
       get: "/v2beta/settings/domain"
@@ -268,6 +289,7 @@ service SettingsService {
     };
 
     option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
+      deprecated: true;
       summary: "Get the domain settings";
       description: "Return the domain settings for the requested context"
       responses: {
@@ -280,6 +302,8 @@ service SettingsService {
   }
 
   // Get the legal and support settings
+  //
+  // Deprecated: please move to the corresponding endpoint under settings service v2. This endpoint will be removed with the next major version of ZITADEL.
   rpc GetLegalAndSupportSettings (GetLegalAndSupportSettingsRequest) returns (GetLegalAndSupportSettingsResponse) {
     option (google.api.http) = {
       get: "/v2beta/settings/legal_support"
@@ -292,6 +316,7 @@ service SettingsService {
     };
 
     option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
+      deprecated: true;
       summary: "Get the legal and support settings";
       description: "Return the legal settings for the requested context"
       responses: {
@@ -304,6 +329,8 @@ service SettingsService {
   }
 
   // Get the lockout settings
+  //
+  // Deprecated: please move to the corresponding endpoint under settings service v2. This endpoint will be removed with the next major version of ZITADEL.
   rpc GetLockoutSettings (GetLockoutSettingsRequest) returns (GetLockoutSettingsResponse) {
     option (google.api.http) = {
       get: "/v2beta/settings/lockout"
@@ -316,6 +343,7 @@ service SettingsService {
     };
 
     option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
+      deprecated: true;
       summary: "Get the lockout settings";
       description: "Return the lockout settings for the requested context, which define when a user will be locked"
       responses: {
@@ -328,6 +356,8 @@ service SettingsService {
   }
 
 // Get the security settings
+  //
+  // Deprecated: please move to the corresponding endpoint under settings service v2. This endpoint will be removed with the next major version of ZITADEL.
   rpc GetSecuritySettings(GetSecuritySettingsRequest) returns (GetSecuritySettingsResponse) {
     option (google.api.http) = {
       get: "/v2beta/settings/security";
@@ -340,12 +370,15 @@ service SettingsService {
     };
 
     option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
+      deprecated: true;
       summary: "Get Security Settings";
       description: "Returns the security settings of the ZITADEL instance."
     };
   }
 
 // Set the security settings
+  //
+  // Deprecated: please move to the corresponding endpoint under settings service v2. This endpoint will be removed with the next major version of ZITADEL.
   rpc SetSecuritySettings(SetSecuritySettingsRequest) returns (SetSecuritySettingsResponse) {
     option (google.api.http) = {
       put: "/v2beta/policies/security";
@@ -359,6 +392,7 @@ service SettingsService {
     };
 
     option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
+      deprecated: true;
       summary: "Set Security Settings";
       description: "Set the security settings of the ZITADEL instance."
     };
@@ -366,6 +400,8 @@ service SettingsService {
 
   // Set Organization Settings
   //
+  // Deprecated: please move to the corresponding endpoint under settings service v2. This endpoint will be removed with the next major version of ZITADEL.
+  //
   // Sets the settings specific to an organization.
   // Organization scopes usernames defines that the usernames have to be unique in the organization scope, can only be changed if the usernames of the users are unique in the scope.
   //
@@ -373,6 +409,7 @@ service SettingsService {
   //   - `iam.policy.write`
   rpc SetOrganizationSettings(SetOrganizationSettingsRequest) returns (SetOrganizationSettingsResponse) {
     option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
+      deprecated: true;
       responses: {
         key: "200";
         value: {
@@ -395,12 +432,15 @@ service SettingsService {
 
   // Delete Organization Settings
   //
+  // Deprecated: please move to the corresponding endpoint under settings service v2. This endpoint will be removed with the next major version of ZITADEL.
+  //
   // Delete the settings specific to an organization.
   //
   // Required permissions:
   //   - `iam.policy.delete`
   rpc DeleteOrganizationSettings(DeleteOrganizationSettingsRequest) returns (DeleteOrganizationSettingsResponse) {
     option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
+      deprecated: true;
       responses: {
         key: "200";
         value: {
@@ -423,6 +463,8 @@ service SettingsService {
 
   // List Organization Settings
   //
+  // Deprecated: please move to the corresponding endpoint under settings service v2. This endpoint will be removed with the next major version of ZITADEL.
+  //
   // Returns a list of organization settings.
   //
   // Required permission:
@@ -441,6 +483,7 @@ service SettingsService {
     };
 
     option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
+      deprecated: true;
       responses: {
         key: "200";
         value: {