docs: Management api documentation (#5301)

* docs: management api documentation

* docs: management api documentation

* docs: management api documentation

* docs: management api documentation

* docs: management api documentation

* docs: management api documentation

* docs: management api documentation

* docs: management api documentation

* docs: management api documentation

* docs: management api documentation

* docs: management api documentation

* docs: management api documentation

* docs: management api documentation

* docs: management api documentation

* docs: management api documentation

* docs: management api documentation

* wording and typos

---------

Co-authored-by: Florian Forster <florian@zitadel.com>

proto/zitadel/admin.proto

@@ -1895,7 +1895,7 @@ service AdminService {
             tags: "Settings";
             tags: "Login Settings";
             tags: "Identity Providers"
-            summary: "Add Linked Identity Providers";
+            summary: "Add Linked Identity Provider";
             description: "Add/link a pre-configured identity provider to the login settings of the instance. This means that it will be shown to the users on the login page. It affects all organizations, without custom login settings."
             responses: {
                 key: "200";
@@ -1919,7 +1919,7 @@ service AdminService {
             tags: "Settings";
             tags: "Login Settings";
             tags: "Identity Providers"
-            summary: "Remove Linked Identity Providers";
+            summary: "Remove Linked Identity Provider";
             description: "Remove an identity provider from the login settings of the instance. This means that it will not be shown to the users on the login page. It affects all organizations, without custom login settings."
             responses: {
                 key: "200";
@@ -2591,7 +2591,7 @@ service AdminService {
 
         option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
             tags: "Message Texts";
-            summary: "Set Default Verify Email Reset Message Text";
+            summary: "Set Default Verify Email Message Text";
             description: "Set the custom text of the verify email user message/email that is overwritten on the instance as settings/database. The text will be sent to the users of all organizations, that do not have a custom text configured. The email is sent when a user adds a new nonverified email address. The Following Variables can be used: {{.Code}} {{.UserName}} {{.FirstName}} {{.LastName}} {{.NickName}} {{.DisplayName}} {{.LastEmail}} {{.VerifiedEmail}} {{.LastPhone}} {{.VerifiedPhone}} {{.PreferredLoginName}} {{.LoginNames}} {{.ChangeDate}} {{.CreationDate}}"
         };
     }
@@ -2608,7 +2608,7 @@ service AdminService {
         option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
             tags: "Message Texts";
             summary: "Reset Custom Verify Email Message Text to Default";
-            description: "Removes the custom text of the email verify user message/email that is overwritten on the instance and triggers the text from the translation files stored in ZITADEL itself. The text will be sent to the users of all organizations, that do not have a custom text configured."
+            description: "Removes the custom text of the email verify message/email that is overwritten on the instance and triggers the text from the translation files stored in ZITADEL itself. The text will be sent to the users of all organizations, that do not have a custom text configured."
         };
     }
 
@@ -2884,7 +2884,7 @@ service AdminService {
         option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
             tags: "Login Texts";
             summary: "Get Default Login Text";
-            description: "Get the default texts for the login and register U of ZITADEL, which are stored as translation files in ZITADEL itself. The text will be shown to the users of all organizations, that do not have a custom text configured."
+            description: "Get the default texts for the login and register UI of ZITADEL, which are stored as translation files in ZITADEL itself. The text will be shown to the users of all organizations, that do not have a custom text configured."
         };
     }
 
@@ -4017,7 +4017,11 @@ message AddOIDCIDPRequest {
 
 message AddOIDCIDPResponse {
     zitadel.v1.ObjectDetails details = 1;
-    string idp_id = 2;
+    string idp_id = 2 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            example: "\"53829026806489455\"";
+        }
+    ];
 }
 
 message AddJWTIDPRequest {
@@ -4763,13 +4767,62 @@ message UpdateLabelPolicyRequest {
             description: "hides the org suffix on the login form if the scope \"urn:zitadel:iam:org:domain:primary:{domainname}\" is set";
         }
     ];
-    string warn_color = 4 [(validate.rules).string = {max_len: 50}];
+    string warn_color = 4 [
-    string background_color = 5 [(validate.rules).string = {max_len: 50}];
+        (validate.rules).string = {max_len: 50},
-    string font_color = 6 [(validate.rules).string = {max_len: 50}];
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
-    string primary_color_dark = 7 [(validate.rules).string = {max_len: 50}];
+            description: "hex value for warn color";
-    string background_color_dark = 8 [(validate.rules).string = { max_len: 50}];
+            example: "\"#CD3D56\"";
-    string warn_color_dark = 9 [(validate.rules).string = { max_len: 50}];
+            max_length: 50;
-    string font_color_dark = 10 [(validate.rules).string = { max_len: 50}];
+        }
+    ];
+    string background_color = 5 [
+        (validate.rules).string = {max_len: 50},
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            description: "hex value for background color";
+            example: "\"#FAFAFA\"";
+            max_length: 50;
+        }
+    ];
+    string font_color = 6 [
+        (validate.rules).string = {max_len: 50},
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            description: "hex value for font color";
+            example: "\"#000000\"";
+            max_length: 50;
+        }
+    ];
+    string primary_color_dark = 7 [
+        (validate.rules).string = {max_len: 50},
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            description: "hex value for the primary color dark theme";
+            example: "\"#BBBAFA\"";
+            max_length: 50;
+        }
+    ];
+    string background_color_dark = 8 [
+        (validate.rules).string = { max_len: 50},
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            description: "hex value for background color dark theme";
+            example: "\"#111827\"";
+            max_length: 50;
+        }
+    ];
+    string warn_color_dark = 9 [
+        (validate.rules).string = { max_len: 50},
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            description: "hex value for warning color dark theme";
+            example: "\"#FF3B5B\"";
+            max_length: 50;
+        }
+    ];
+    string font_color_dark = 10 [
+        (validate.rules).string = { max_len: 50},
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            description: "hex value for font color dark theme";
+            example: "\"#FFFFFF\"";
+            max_length: 50;
+        }
+    ];
     bool disable_watermark = 11;
 }
 
@@ -5034,22 +5087,22 @@ message UpdatePasswordComplexityPolicyRequest {
     ];
     bool has_uppercase = 2 [
         (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
-            description: "defines if the password MUST contain an upper case letter"
+            description: "Defines if the password MUST contain an upper case letter"
         }
     ];
     bool has_lowercase = 3 [
         (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
-            description: "defines if the password MUST contain a lowercase letter"
+            description: "Defines if the password MUST contain a lowercase letter"
         }
     ];
     bool has_number = 4 [
         (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
-            description: "defines if the password MUST contain a number"
+            description: "Defines if the password MUST contain a number"
         }
     ];
     bool has_symbol = 5 [
         (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
-            description: "defines if the password MUST contain a symbol. E.g. \"$\""
+            description: "Defines if the password MUST contain a symbol. E.g. \"$\""
         }
     ];
 }
@@ -5135,7 +5188,11 @@ message UpdatePrivacyPolicyResponse {
 }
 
 message AddNotificationPolicyRequest {
-    bool password_change = 1;
+    bool password_change = 1 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            description: "If set to true the users will get a notification whenever their password has been changed.";
+        }
+    ];
 }
 
 message AddNotificationPolicyResponse {
@@ -5150,7 +5207,11 @@ message GetNotificationPolicyResponse {
 }
 
 message UpdateNotificationPolicyRequest {
-   bool password_change = 1;
+   bool password_change = 1 [
+       (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+           description: "If set to true the users will get a notification whenever their password has been changed.";
+       }
+   ];
 }
 
 message UpdateNotificationPolicyResponse {

proto/zitadel/auth.proto

@@ -562,7 +562,7 @@ service AuthService {
         option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
             tags: "User Social Login"
             summary: "List Social Logins";
-            description: "Returns a list of all liked identity providers/social logins of the user. (e. Google, Microsoft, AzureAD, etc.)"
+            description: "Returns a list of all linked identity providers/social logins of the user. (e. Google, Microsoft, AzureAD, etc.)"
         };
     }
 
@@ -870,7 +870,7 @@ service AuthService {
         option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
             tags: "User Memberships"
             summary: "List My ZITADEL Permissions";
-            description: "Show all the permissions my user has in ZITADEL (ZITADEL Manager). The limit should always be set, there is a default limit set by the service"
+            description: "Show all the permissions my user has in ZITADEL (ZITADEL Manager)."
         };
     }
 

proto/zitadel/auth_n_key.proto

@@ -17,6 +17,7 @@ message Key {
     zitadel.v1.ObjectDetails details = 2;
     KeyType type = 3 [
         (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            example: "\"KEY_TYPE_JSON\"";
             description: "the file type of the key";
         }
     ];

proto/zitadel/idp.proto

@@ -95,6 +95,7 @@ message IDPLoginPolicyLink {
     ];
     IDPType idp_type = 3 [
         (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            example: "[\"IDP_TYPE_OIDC\"]"
             description: "the authorization framework of the identity provider";
         }
     ];

proto/zitadel/member.proto

@@ -23,13 +23,13 @@ message Member {
     ];
     string preferred_login_name = 4 [
         (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
-            example: "\"gigi@caos.ch\"";
+            example: "\"gigi@zitadel.com\"";
             description: "preferred login name of the user"
         }
     ];
     string email = 5 [
         (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
-            example: "\"gigi@caos.ch\"";
+            example: "\"gigi@zitadel.com\"";
             description: "preferred login name of the user"
         }
     ];
@@ -108,7 +108,7 @@ message EmailQuery {
         (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
             description: "email address of the user. (spec: https://tools.ietf.org/html/rfc2822#section-3.4.1)"
             max_length: 200;
-            example: "\"gigi@caos.ch\"";
+            example: "\"gigi@zitadel.com\"";
         }
     ];
     zitadel.v1.TextQueryMethod method = 2 [

proto/zitadel/policy.proto

@@ -316,7 +316,7 @@ message LockoutPolicy {
     zitadel.v1.ObjectDetails details = 1;
     uint64 max_password_attempts = 2 [
         (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."
+            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\""
         }
     ];
@@ -350,5 +350,9 @@ message PrivacyPolicy {
 message NotificationPolicy {
     zitadel.v1.ObjectDetails details = 1;
     bool is_default = 2;
-    bool password_change = 3;
+    bool password_change = 3 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            description: "If set to true the users will get a notification whenever their password has been changed.";
+        }
+    ];
 }

proto/zitadel/project.proto

@@ -17,7 +17,7 @@ message Project {
     zitadel.v1.ObjectDetails details = 2;
     string name = 3 [
         (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
-            example: "\"ZITADEL\""
+            example: "\"MyProject\""
         }
     ];
     ProjectState state = 4 [
@@ -79,7 +79,7 @@ message GrantedProject {
     ];
     string project_owner_name = 9 [
         (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
-            example: "\"CAOS AG\""
+            example: "\"ZITADEL\""
         }
     ];