docs: correct api v2 docs for zitadel v4 (#10249)

# Which Problems Are Solved

As documentation is published from the main branch and the releases get
created from another branch, they are not always correctly equal.

# How the Problems Are Solved

Add previously removed docs again to the documentation.
Add deprecation notes on all replaced endpoints related to
administrators, authentications and projects.

## Deprecated endpoints

- Management service
  - to Organization service v2
    - GetOrgByDomainGlobal
  - to User service v2
    - AddMachineUser
    - UpdateMachine
    - GenerateMachineSecret
    - RemoveMachineSecret
    - GetMachineKeyByIDs
    - ListMachineKeys
    - AddMachineKey
    - RemoveMachineKey
    - UpdateUserName
    - SetUserMetadata
    - BulkSetUserMetadata
    - ListUserMetadata
    - GetUserMetadata
    - RemoveUserMetadata
    - BulkRemoveUserMetadata
    - UpdateHumanPhone
    - GetPersonalAccessTokenByIDs
    - ListPersonalAccessTokens
    - AddPersonalAccessToken
    - RemovePersonalAccessToken
  - to Application service v2beta
    - ListAppKeys
  - to Project service v2beta
    - GetProjectByID
    - GetGrantedProjectByID
    - ListProjects
    - ListGrantedProjects
    - ListGrantedProjectRoles
    - AddProject
    - UpdateProject
    - DeactivateProject
    - ReactivateProject
    - RemoveProject
    - ListProjectRoles
    - AddProjectRole
    - BulkAddProjectRoles
    - UpdateProjectRole
    - RemoveProjectRole
    - GetProjectGrantByID
    - ListProjectGrants
    - ListAllProjectGrants
    - AddProjectGrant
    - UpdateProjectGrant
    - DeactivateProjectGrant
    - ReactivateProjectGrant
    - RemoveProjectGrant
  - to Internal Permission service v2beta
    - ListUserMemberships
    - ListOrgMembers
    - AddOrgMember
    - UpdateOrgMember
    - RemoveOrgMember
    - ListProjectMembers
    - AddProjectMember
    - UpdateProjectMember
    - RemoveProjectMember
    - ListProjectGrantMembers
    - AddProjectGrantMember
    - UpdateProjectGrantMember
    - RemoveProjectGrantMember
- Admin service
  - to Instance service v2
    - GetMyInstance
    - ListInstanceDomains
    - ListInstanceTrustedDomains
    - AddInstanceTrustedDomain
    - RemoveInstanceTrustedDomain
  - to Organization service v2
    - GetOrgByID
    - IsOrgUnique
    - GetDefaultOrg
  - to Internal Permission service v2beta
    - ListIAMMembers
    - AddIAMMember
    - UpdateIAMMember
    - RemoveIAMMember

# Additional Changes

None

# Additional Context

Related to #10112

---------

Co-authored-by: Gayathri Vijayan <66356931+grvijayan@users.noreply.github.com>
Co-authored-by: Gayathri Vijayan <gayathri+github@zitadel.com>
Co-authored-by: Marco A. <marco@zitadel.com>

docs/sidebars.js

@@ -7,6 +7,7 @@ const sidebar_api_system = require("./docs/apis/resources/system/sidebar.ts").de
 const sidebar_api_user_service_v2 = require("./docs/apis/resources/user_service_v2/sidebar.ts").default
 const sidebar_api_session_service_v2 = require("./docs/apis/resources/session_service_v2/sidebar.ts").default
 const sidebar_api_oidc_service_v2 = require("./docs/apis/resources/oidc_service_v2/sidebar.ts").default
+const sidebar_api_saml_service_v2 = require("./docs/apis/resources/saml_service_v2/sidebar.ts").default
 const sidebar_api_settings_service_v2 = require("./docs/apis/resources/settings_service_v2/sidebar.ts").default
 const sidebar_api_feature_service_v2 = require("./docs/apis/resources/feature_service_v2/sidebar.ts").default
 const sidebar_api_org_service_v2 = require("./docs/apis/resources/org_service_v2/sidebar.ts").default
@@ -17,7 +18,7 @@ const sidebar_api_project_service_v2 = require("./docs/apis/resources/project_se
 const sidebar_api_webkey_service_v2 = require("./docs/apis/resources/webkey_service_v2/sidebar.ts").default
 const sidebar_api_instance_service_v2 = require("./docs/apis/resources/instance_service_v2/sidebar.ts").default
 const sidebar_api_authorization_service_v2 = require("./docs/apis/resources/authorization_service_v2/sidebar.ts").default
-const sidebar_api_permission_service_v2 = require("./docs/apis/resources/internal_permission_service_v2/sidebar.ts").default
+const sidebar_api_internal_permission_service_v2 = require("./docs/apis/resources/internal_permission_service_v2/sidebar.ts").default
 const sidebar_api_app_v2 = require("./docs/apis/resources/application_service_v2/sidebar.ts").default
 
 module.exports = {
@@ -710,6 +711,18 @@ module.exports = {
               },
               items: sidebar_api_oidc_service_v2,
             },
+            {
+              type: "category",
+              label: "SAML",
+              link: {
+                type: "generated-index",
+                title: "SAML Service API",
+                slug: "/apis/resources/saml_service_v2",
+                description:
+                  "Get SAML Request details and create responses.\n",
+              },
+              items: sidebar_api_saml_service_v2,
+            },
             {
               type: "category",
               label: "Settings",
@@ -872,17 +885,17 @@ module.exports = {
             },
             {
               type: "category",
-              label: "Permissions (Beta)",
+              label: "Internal Permissions (Beta)",
               link: {
                 type: "generated-index",
-                title: "Permission Service API (Beta)",
+                title: "Internal Permission Service API (Beta)",
-                slug: "/apis/resources/permission_service_v2",
+                slug: "/apis/resources/internal_permission_service_v2",
                 description:
                     "This API is intended to manage internal permissions in ZITADEL.\n" +
                     "\n"+
                     "This API is in beta state. It can AND will continue breaking until a stable version is released.\n"
               },
-              items: sidebar_api_permission_service_v2,
+              items: sidebar_api_internal_permission_service_v2,
             },
           ],
         },

proto/zitadel/admin.proto

@@ -291,6 +291,11 @@ service AdminService {
         };
     }
 
+    // Get My Instance
+    //
+    // Deprecated: use [instance service v2 GetInstance](apis/resources/instance_service_v2/zitadel-instance-v-2-beta-instance-service-get-instance.api.mdx) instead.
+    //
+    // Returns the details about the current instance such as the name, version, domains, etc.
     rpc GetMyInstance(GetMyInstanceRequest) returns (GetMyInstanceResponse) {
         option (google.api.http) = {
             get: "/instances/me";
@@ -302,11 +307,15 @@ service AdminService {
 
         option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
             tags: "Instance";
-            summary: "Get My Instance";
+            deprecated: true;
-            description: "Returns the details about the current instance such as the name, version, domains, etc."
         };
     }
 
+    // List Instance Domains
+    //
+    // Deprecated: use [instance service v2 GetInstance](apis/resources/instance_service_v2/zitadel-instance-v-2-beta-instance-service-get-instance.api.mdx) instead.
+    //
+    // Returns a list of domains that are configured for this ZITADEL instance. These domains are the URLs where ZITADEL is running.
     rpc ListInstanceDomains(ListInstanceDomainsRequest) returns (ListInstanceDomainsResponse) {
         option (google.api.http) = {
             post: "/domains/_search";
@@ -318,11 +327,15 @@ service AdminService {
 
         option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
             tags: "Instance";
-            summary: "List Instance Domains";
+            deprecated: true;
-            description: "Returns a list of domains that are configured for this ZITADEL instance. These domains are the URLs where ZITADEL is running."
         };
     }
 
+    // List Instance Trusted Domains
+    //
+    // Deprecated: use [instance service v2 ListTrustedDomains](apis/resources/instance_service_v2/zitadel-instance-v-2-beta-instance-service-list-trusted-domains.api.mdx) instead.
+    //
+    // Returns a list of domains that are configured for this ZITADEL instance. These domains are trusted to be used as public hosts.
     rpc ListInstanceTrustedDomains(ListInstanceTrustedDomainsRequest) returns (ListInstanceTrustedDomainsResponse) {
         option (google.api.http) = {
             post: "/trusted_domains/_search";
@@ -334,11 +347,15 @@ service AdminService {
 
         option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
             tags: "Instance";
-            summary: "List Instance Trusted Domains";
+            deprecated: true;
-            description: "Returns a list of domains that are configured for this ZITADEL instance. These domains are trusted to be used as public hosts."
         };
     }
 
+    // Add an Instance Trusted Domain
+    //
+    // Deprecated: use [instance service v2 ListTrustedDomains](apis/resources/instance_service_v2/zitadel-instance-v-2-beta-instance-service-add-trusted-domain.api.mdx) instead.
+    //
+    // Add a domain to the list configured for this ZITADEL instance. These domains are trusted to be used as public hosts.
     rpc AddInstanceTrustedDomain(AddInstanceTrustedDomainRequest) returns (AddInstanceTrustedDomainResponse) {
         option (google.api.http) = {
             post: "/trusted_domains";
@@ -351,11 +368,15 @@ service AdminService {
 
         option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
             tags: "Instance";
-            summary: "Add an Instance Trusted Domain";
+            deprecated: true;
-            description: "Returns a list of domains that are configured for this ZITADEL instance. These domains are trusted to be used as public hosts."
         };
     }
 
+    // Remove an Instance Trusted Domain
+    //
+    // Deprecated: use [instance service v2 ListTrustedDomains](apis/resources/instance_service_v2/zitadel-instance-v-2-beta-instance-service-remove-trusted-domain.api.mdx) instead.
+    //
+    // Removes a domain from the list configured for this ZITADEL instance. These domains are trusted to be used as public hosts.
     rpc RemoveInstanceTrustedDomain(RemoveInstanceTrustedDomainRequest) returns (RemoveInstanceTrustedDomainResponse) {
         option (google.api.http) = {
             delete: "/trusted_domains/{domain}";
@@ -367,8 +388,7 @@ service AdminService {
 
         option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
             tags: "Instance";
-            summary: "Remove an Instance Trusted Domain";
+            deprecated: true;
-            description: "Returns a list of domains that are configured for this ZITADEL instance. These domains are trusted to be used as public hosts."
         };
     }
 
@@ -1153,6 +1173,11 @@ service AdminService {
         };
     }
 
+    // Get Organization By ID
+    //
+    // Deprecated: use [organization service v2 ListOrganizations](apis/resources/org_service_v2/organization-service-list-organizations.api.mdx) instead.
+    //
+    // Returns an organization by its ID. Make sure the user has the permissions to access the organization.
     rpc GetOrgByID(GetOrgByIDRequest) returns (GetOrgByIDResponse) {
         option (google.api.http) = {
             get: "/orgs/{id}";
@@ -1164,8 +1189,7 @@ service AdminService {
 
         option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
             tags: "Organizations";
-            summary: "Get Organization By ID";
+            deprecated: true;
-            description: "Returns an organization by its ID. Make sure the user has the permissions to access the organization."
             responses: {
                 key: "200";
                 value: {
@@ -1175,6 +1199,11 @@ service AdminService {
         };
     }
 
+    // Is Organization Unique
+    //
+    // Deprecated: use [organization service v2 ListOrganizations](apis/resources/org_service_v2/organization-service-list-organizations.api.mdx) instead.
+    //
+    // Checks if an organization with the searched parameters already exists or not.
     rpc IsOrgUnique(IsOrgUniqueRequest) returns (IsOrgUniqueResponse) {
         option (google.api.http) = {
             get: "/orgs/_is_unique";
@@ -1186,8 +1215,7 @@ service AdminService {
 
         option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
             tags: "Organizations";
-            summary: "Is Organization Unique";
+            deprecated: true;
-            description: "Checks if an organization with the searched parameters already exists or not."
             responses: {
                 key: "200";
                 value: {
@@ -1220,6 +1248,11 @@ service AdminService {
         };
     }
 
+    // Get Default Organization
+    //
+    // Deprecated: use [organization service v2 ListOrganizations](apis/resources/org_service_v2/organization-service-list-organizations.api.mdx) instead.
+    //
+    // Get the default organization of the ZITADEL instance. If no specific organization is given on the register form, a user will be registered to the default organization.
     rpc GetDefaultOrg(GetDefaultOrgRequest) returns (GetDefaultOrgResponse) {
         option (google.api.http) = {
             get: "/orgs/default";
@@ -1232,13 +1265,16 @@ service AdminService {
         option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
             tags: "Organizations";
             tags: "Settings";
-            summary: "Get Default Organization";
+            deprecated: true;
-            description: "Get the default organization of the ZITADEL instance. If no specific organization is given on the register form, a user will be registered to the default organization."
         };
     }
 
-    // Deprecated: use ListOrganization [apis/resources/org_service_v2beta/organization-service-list-organizations.api.mdx] API instead
+    // Search Organizations
-    rpc ListOrgs(ListOrgsRequest) returns (ListOrgsResponse) {
+    //
+    // Deprecated: use [organization service v2 ListOrganizations](apis/resources/org_service_v2/organization-service-list-organizations.api.mdx) instead.
+    //
+    // Returns a list of organizations that match the requesting filters. All filters are applied with an AND condition.
+     rpc ListOrgs(ListOrgsRequest) returns (ListOrgsResponse) {
         option (google.api.http) = {
             post: "/orgs/_search";
             body: "*";
@@ -1250,8 +1286,6 @@ service AdminService {
 
         option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
             tags: "Organizations";
-            summary: "Search Organization";
-            description: "Returns a list of organizations that match the requesting filters. All filters are applied with an AND condition."
             responses: {
                 key: "200";
                 value: {
@@ -1273,7 +1307,11 @@ service AdminService {
         };
     }
 
-    // Deprecated: use CreateOrganization [apis/resources/org_service_v2beta/organization-service-create-organization.api.mdx] API instead
+    // Setup Organization
+    //
+    // Deprecated: use [organization service v2 CreateOrganization](apis/resources/org_service_v2beta/zitadel-org-v-2-beta-organization-service-create-organization.api.mdx) instead.
+    //
+    // Create a new organization with an administrative user. If no specific roles are sent for the first user, the user will get the role ORG_OWNER.
     rpc SetUpOrg(SetUpOrgRequest) returns (SetUpOrgResponse) {
         option (google.api.http) = {
             post: "/orgs/_setup";
@@ -1286,8 +1324,6 @@ service AdminService {
 
         option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
             tags: "Organizations";
-            summary: "Setup Organization";
-            description: "Create a new organization with an administrative user. If no specific roles are sent for the first user, the user will get the role ORG_OWNER."
             responses: {
                 key: "200";
                 value: {
@@ -1309,7 +1345,11 @@ service AdminService {
         };
     }
 
-    // Deprecated: use DeleteOrganization [apis/resources/org_service_v2beta/organization-service-delete-organization.api.mdx] API instead
+    // Remove Organization
+    //
+    // Deprecated: use [organization service v2 DeleteOrganization](apis/resources/org_service_v2beta/zitadel-org-v-2-beta-organization-service-delete-organization.api.mdx) instead.
+    //
+    // Deletes the organization and all its resources (Users, Projects, Grants to and from the org). Users of this organization will not be able to log in.
     rpc RemoveOrg(RemoveOrgRequest) returns (RemoveOrgResponse) {
         option (google.api.http) = {
             delete: "/orgs/{org_id}"
@@ -1320,8 +1360,6 @@ service AdminService {
         };
         option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
             tags: "Organizations";
-            summary: "Remove Organization";
-            description: "Deletes the organization and all its resources (Users, Projects, Grants to and from the org). Users of this organization will not be able to log in."
             responses: {
                 key: "200";
                 value: {
@@ -1343,7 +1381,6 @@ service AdminService {
         };
     }
 
-
     rpc GetIDPByID(GetIDPByIDRequest) returns (GetIDPByIDResponse) {
         option (google.api.http) = {
             get: "/idps/{id}";
@@ -4011,6 +4048,11 @@ service AdminService {
         };
     }
 
+    // List IAM Members
+    //
+    // Deprecated: use [ListAdministrators](apis/resources/internal_permission_service_v2/zitadel-internal-permission-v-2-beta-internal-permission-service-list-administrators.api.mdx) instead.
+    //
+    // Members are users with permission to administrate ZITADEL on different levels. This request returns all users with memberships on the instance level, matching the search queries. The search queries will be AND linked.
     rpc ListIAMMembers(ListIAMMembersRequest) returns (ListIAMMembersResponse) {
         option (google.api.http) = {
             post: "/members/_search";
@@ -4024,8 +4066,7 @@ service AdminService {
         option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
             tags: "Members";
             tags: "ZITADEL Administrators";
-            summary: "List IAM Members";
+            deprecated: true;
-            description: "Members are users with permission to administrate ZITADEL on different levels. This request returns all users with memberships on the instance level, matching the search queries. The search queries will be AND linked."
             responses: {
                 key: "200";
                 value: {
@@ -4035,8 +4076,11 @@ service AdminService {
         };
     }
 
-    //Adds a user to the membership list of ZITADEL with the given roles
+    // Add IAM Member
-    // undefined roles will be dropped
+    //
+    // Deprecated: use [CreateAdministrator](apis/resources/internal_permission_service_v2/zitadel-internal-permission-v-2-beta-internal-permission-service-create-administrator.api.mdx) instead.
+    //
+    // Members are users with permission to administrate ZITADEL on different levels. This request adds a new user to the members list with one or multiple roles.
     rpc AddIAMMember(AddIAMMemberRequest) returns (AddIAMMemberResponse) {
         option (google.api.http) = {
             post: "/members";
@@ -4050,8 +4094,7 @@ service AdminService {
         option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
             tags: "Members";
             tags: "ZITADEL Administrators";
-            summary: "Add IAM Member";
+            deprecated: true;
-            description: "Members are users with permission to administrate ZITADEL on different levels. This request adds a new user to the members list with one or multiple roles."
             responses: {
                 key: "200";
                 value: {
@@ -4072,6 +4115,11 @@ service AdminService {
         };
     }
 
+    // Update IAM Member
+    //
+    // Deprecated: use [UpdateAdministrator](apis/resources/internal_permission_service_v2/zitadel-internal-permission-v-2-beta-internal-permission-service-update-administrator.api.mdx) instead.
+    //
+    // Members are users with permission to administrate ZITADEL on different levels. This request changes the roles of an existing member. The whole roles list will be updated. Make sure to include roles that you don't want to change (remove).
     rpc UpdateIAMMember(UpdateIAMMemberRequest) returns (UpdateIAMMemberResponse) {
         option (google.api.http) = {
             put: "/members/{user_id}";
@@ -4085,8 +4133,7 @@ service AdminService {
         option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
             tags: "Members";
             tags: "ZITADEL Administrators";
-            summary: "Update IAM Member";
+            deprecated: true;
-            description: "Members are users with permission to administrate ZITADEL on different levels. This request changes the roles of an existing member. The whole roles list will be updated. Make sure to include roles that you don't want to change (remove)."
             responses: {
                 key: "200";
                 value: {
@@ -4107,6 +4154,11 @@ service AdminService {
         };
     }
 
+    // Remove IAM Member
+    //
+    // Deprecated: use [DeleteAdministrator](apis/resources/internal_permission_service_v2/zitadel-internal-permission-v-2-beta-internal-permission-service-delete-administrator.api.mdx) instead.
+    //
+    // Members are users with permission to administrate ZITADEL on different levels. This request removes a user from the members list on an instance level. The user can still have roles on another level (organization, project).
     rpc RemoveIAMMember(RemoveIAMMemberRequest) returns (RemoveIAMMemberResponse) {
         option (google.api.http) = {
             delete: "/members/{user_id}";
@@ -4119,8 +4171,7 @@ service AdminService {
         option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
             tags: "Members";
             tags: "ZITADEL Administrators";
-            summary: "Remove IAM Member";
+            deprecated: true;
-            description: "Members are users with permission to administrate ZITADEL on different levels. This request removes a user from the members list on an instance level. The user can still have roles on another level (organization, project)"
             responses: {
                 key: "200";
                 value: {

proto/zitadel/instance/v2beta/instance_service.proto

@@ -138,7 +138,7 @@ service InstanceService {
   //
   // Returns the instance in the current context.
   //
-  // The instace_id in the input message will be used in the future.
+  // The instance_id in the input message will be used in the future.
   //
   // Required permissions:
   //   - `iam.read`

proto/zitadel/system.proto

@@ -250,9 +250,11 @@ service SystemService {
     };
   }
 
-  // Returns the custom domains of an instance
+  // List Domains
-  // Checks if a domain exists
+  //
-  // Deprecated: Use the Admin APIs ListInstanceDomains on the admin API instead
+  // Deprecated: use [instance service v2 ListCustomDomains](apis/resources/instance_service_v2/zitadel-instance-v-2-beta-instance-service-list-custom-domains.api.mdx) instead.
+  //
+  // Returns the custom domains of an instance.
   rpc ListDomains(ListDomainsRequest) returns (ListDomainsResponse) {
     option (google.api.http) = {
       post: "/instances/{instance_id}/domains/_search";

proto/zitadel/user/v2/user_service.proto

@@ -134,6 +134,13 @@ service UserService {
   // Required permission:
   //   - user.write
   rpc CreateUser (CreateUserRequest) returns (CreateUserResponse) {
+    option (google.api.http) = {
+      // The /new path segment does not follow Zitadels API design.
+      // The only reason why it is used here is to avoid a conflict with the ListUsers endpoint, which already handles POST /v2/users.
+      post: "/v2/users/new"
+      body: "*"
+    };
+
     option (zitadel.protoc_gen_zitadel.v2.options) = {
       auth_option: {
         permission: "authenticated"
@@ -163,6 +170,8 @@ service UserService {
 
   // Create a new human user
   //
+  // Deprecated: Use [CreateUser](apis/resources/user_service_v2/user-service-create-user.api.mdx) to create a new user of type human instead.
+  //
   // Create/import a new user with the type human. The newly created user will get a verification email if either the email address is not marked as verified and you did not request the verification to be returned.
   rpc AddHumanUser (AddHumanUserRequest) returns (AddHumanUserResponse) {
     option (google.api.http) = {
@@ -181,6 +190,7 @@ service UserService {
     };
 
     option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
+      deprecated: true;
       responses: {
         key: "200"
         value: {
@@ -261,6 +271,8 @@ service UserService {
 
   // Change the user email
   //
+  // Deprecated: [Update the users email field](apis/resources/user_service_v2/user-service-update-user.api.mdx).
+  //
   // Change the email address of a user. If the state is set to not verified, a verification code will be generated, which can be either returned or sent to the user by email..
   rpc SetEmail (SetEmailRequest) returns (SetEmailResponse) {
     option (google.api.http) = {
@@ -275,6 +287,7 @@ service UserService {
     };
 
     option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
+      deprecated: true;
       responses: {
         key: "200"
         value: {
@@ -381,6 +394,8 @@ service UserService {
 
   // Set the user phone
   //
+  // Deprecated: [Update the users phone field](apis/resources/user_service_v2/user-service-update-user.api.mdx).
+  //
   // Set the phone number of a user. If the state is set to not verified, a verification code will be generated, which can be either returned or sent to the user by sms..
   rpc SetPhone(SetPhoneRequest) returns (SetPhoneResponse) {
     option (google.api.http) = {
@@ -395,6 +410,7 @@ service UserService {
     };
 
     option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
+      deprecated: true;
       responses: {
         key: "200"
         value: {
@@ -412,6 +428,8 @@ service UserService {
 
   // Delete the user phone
   //
+  // Deprecated: [Update the users phone field](apis/resources/user_service_v2/user-service-update-user.api.mdx) to remove the phone number.
+  //
   // Delete the phone number of a user.
   rpc RemovePhone(RemovePhoneRequest) returns (RemovePhoneResponse) {
     option (google.api.http) = {
@@ -426,6 +444,7 @@ service UserService {
     };
 
     option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
+      deprecated: true;
       responses: {
         key: "200"
         value: {
@@ -441,7 +460,9 @@ service UserService {
     };
   }
 
-  // Resend code to verify user phone
+  // Resend code to verify user phone number
+  //
+  // Resend code to verify user phone number.
   rpc ResendPhoneCode (ResendPhoneCodeRequest) returns (ResendPhoneCodeResponse) {
     option (google.api.http) = {
       post: "/v2/users/{user_id}/phone/resend"
@@ -470,9 +491,9 @@ service UserService {
     };
   }
 
-  // Verify the phone
+  // Verify the phone number
   //
-  // Verify the phone with the generated code..
+  // Verify the phone number with the generated code.
   rpc VerifyPhone (VerifyPhoneRequest) returns (VerifyPhoneResponse) {
     option (google.api.http) = {
       post: "/v2/users/{user_id}/phone/verify"
@@ -510,6 +531,10 @@ service UserService {
   // Required permission:
   //   - user.write
   rpc UpdateUser(UpdateUserRequest) returns (UpdateUserResponse) {
+    option (google.api.http) = {
+      patch: "/v2/users/{user_id}"
+      body: "*"
+    };
 
     option (zitadel.protoc_gen_zitadel.v2.options) = {
       auth_option: {
@@ -551,7 +576,9 @@ service UserService {
 
   // Update Human User
   //
-  // Update all information from a user..
+  // Deprecated: Use [UpdateUser](apis/resources/user_service_v2/user-service-update-user.api.mdx) to update a user of type human instead.
+  //
+  // Update all information from a user.
   rpc UpdateHumanUser(UpdateHumanUserRequest) returns (UpdateHumanUserResponse) {
     option (google.api.http) = {
       put: "/v2/users/human/{user_id}"
@@ -565,6 +592,7 @@ service UserService {
     };
 
     option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
+      deprecated: true;
       responses: {
         key: "200"
         value: {
@@ -1352,6 +1380,8 @@ service UserService {
 
   // Change password
   //
+  // Deprecated: [Update the users password](apis/resources/user_service_v2/user-service-update-user.api.mdx) instead.
+  //
   // Change the password of a user with either a verification code or the current password..
   rpc SetPassword (SetPasswordRequest) returns (SetPasswordResponse) {
     option (google.api.http) = {
@@ -1366,6 +1396,7 @@ service UserService {
     };
 
     option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
+      deprecated: true;
       responses: {
         key: "200"
         value: {
@@ -1392,6 +1423,11 @@ service UserService {
   // Required permission:
   //   - user.write
   rpc AddSecret(AddSecretRequest) returns (AddSecretResponse) {
+    option (google.api.http) = {
+      post: "/v2/users/{user_id}/secret"
+      body: "*"
+    };
+
     option (zitadel.protoc_gen_zitadel.v2.options) = {
       auth_option: {
         permission: "authenticated"
@@ -1426,6 +1462,10 @@ service UserService {
   // Required permission:
   //   - user.write
   rpc RemoveSecret(RemoveSecretRequest) returns (RemoveSecretResponse) {
+    option (google.api.http) = {
+      delete: "/v2/users/{user_id}/secret"
+    };
+
     option (zitadel.protoc_gen_zitadel.v2.options) = {
       auth_option: {
         permission: "authenticated"
@@ -1451,6 +1491,11 @@ service UserService {
   // Required permission:
   //   - user.write
   rpc AddKey(AddKeyRequest) returns (AddKeyResponse) {
+    option (google.api.http) = {
+      post: "/v2/users/{user_id}/keys"
+      body: "*"
+    };
+
     option (zitadel.protoc_gen_zitadel.v2.options) = {
       auth_option: {
         permission: "authenticated"
@@ -1485,6 +1530,10 @@ service UserService {
   // Required permission:
   //   - user.write
   rpc RemoveKey(RemoveKeyRequest) returns (RemoveKeyResponse) {
+    option (google.api.http) = {
+      delete: "/v2/users/{user_id}/keys/{key_id}"
+    };
+
     option (zitadel.protoc_gen_zitadel.v2.options) = {
       auth_option: {
         permission: "authenticated"
@@ -1509,6 +1558,11 @@ service UserService {
   // Required permission:
   //   - user.read
   rpc ListKeys(ListKeysRequest) returns (ListKeysResponse) {
+    option (google.api.http) = {
+      post: "/v2/users/keys/search"
+      body: "*"
+    };
+
     option (zitadel.protoc_gen_zitadel.v2.options) = {
       auth_option: {
         permission: "authenticated"
@@ -1540,6 +1594,11 @@ service UserService {
   // Required permission:
   //   - user.write
   rpc AddPersonalAccessToken(AddPersonalAccessTokenRequest) returns (AddPersonalAccessTokenResponse) {
+    option (google.api.http) = {
+      post: "/v2/users/{user_id}/pats"
+      body: "*"
+    };
+
     option (zitadel.protoc_gen_zitadel.v2.options) = {
       auth_option: {
         permission: "authenticated"
@@ -1574,6 +1633,10 @@ service UserService {
   // Required permission:
   //   - user.write
   rpc RemovePersonalAccessToken(RemovePersonalAccessTokenRequest) returns (RemovePersonalAccessTokenResponse) {
+    option (google.api.http) = {
+      delete: "/v2/users/{user_id}/pats/{token_id}"
+    };
+
     option (zitadel.protoc_gen_zitadel.v2.options) = {
       auth_option: {
         permission: "authenticated"
@@ -1598,6 +1661,11 @@ service UserService {
   // Required permission:
   //   - user.read
   rpc ListPersonalAccessTokens(ListPersonalAccessTokensRequest) returns (ListPersonalAccessTokensResponse) {
+    option (google.api.http) = {
+      post: "/v2/users/pats/search"
+      body: "*"
+    };
+
     option (zitadel.protoc_gen_zitadel.v2.options) = {
       auth_option: {
         permission: "authenticated"
@@ -1671,6 +1739,7 @@ service UserService {
   // Create an invite code for a user to initialize their first authentication method (password, passkeys, IdP) depending on the organization's available methods.
   // If an invite code has been created previously, it's url template and application name will be used as defaults for the new code.
   // The new code will overwrite the previous one and make it invalid.
+  // Note: It is possible to reissue a new code only when the previous code has expired, or when the user provides a wrong code three or more times during verification.
   rpc CreateInviteCode (CreateInviteCodeRequest) returns (CreateInviteCodeResponse) {
     option (google.api.http) = {
       post: "/v2/users/{user_id}/invite_code"