Revert "fix: correct user v2 api docs for v3 (#10112)"

This reverts commit 5da5ccda5c.

proto/zitadel/management.proto

@@ -493,6 +493,8 @@ service ManagementService {
 
     // Create User (Machine)
     //
+    // Deprecated: use [user service v2 CreateUser](apis/resources/user_service_v2/user-service-create-user.api.mdx) to create a user of type machine instead.
+    //
     // Create a new user with the type machine for your API, service or device. These users are used for non-interactive authentication flows.
     rpc AddMachineUser(AddMachineUserRequest) returns (AddMachineUserResponse) {
         option (google.api.http) = {
@@ -505,6 +507,7 @@ service ManagementService {
         };
 
         option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
+            deprecated: true;
             tags: "Users";
             tags: "User Machine";
             responses: {
@@ -690,6 +693,8 @@ service ManagementService {
 
     // Change user name
     //
+    // Deprecated: use [user service v2 UpdateUser](apis/resources/user_service_v2/user-service-update-user.api.mdx) instead.
+    //
     // Change the username of the user. Be aware that the user has to log in with the newly added username afterward
     rpc UpdateUserName(UpdateUserNameRequest) returns (UpdateUserNameResponse) {
         option (google.api.http) = {
@@ -703,6 +708,7 @@ service ManagementService {
 
         option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
             tags: "Users";
+            deprecated: true;
             responses: {
                 key: "200"
                 value: {
@@ -1118,6 +1124,8 @@ service ManagementService {
 
     // Update User Phone (Human)
     //
+    // Deprecated: use [user service v2 SetPhone](apis/resources/user_service_v2/user-service-update-user.api.mdx) instead.
+    //
     // Change the phone number of a user. If the state is set to not verified, the user will get an SMS to verify (if a notification provider is configured). The phone number is only for informational purposes and to send messages, not for Authentication (2FA).
     rpc UpdateHumanPhone(UpdateHumanPhoneRequest) returns (UpdateHumanPhoneResponse) {
         option (google.api.http) = {
@@ -1132,6 +1140,7 @@ service ManagementService {
         option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
             tags: "Users";
             tags: "User Human";
+            deprecated: true;
             responses: {
                 key: "200"
                 value: {
@@ -1647,6 +1656,8 @@ service ManagementService {
 
     // Update Machine User
     //
+    // Deprecated: use [user service v2 UpdateUser](apis/resources/user_service_v2/user-service-update-user.api.mdx) to update a user of type machine instead.
+    //
     // Change a service account/machine user. It is used for accounts with non-interactive authentication possibilities.
     rpc UpdateMachine(UpdateMachineRequest) returns (UpdateMachineResponse) {
         option (google.api.http) = {
@@ -1659,6 +1670,7 @@ service ManagementService {
         };
 
         option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
+            deprecated: true;
             tags: "Users";
             tags: "User Machine";
             responses: {
@@ -1680,6 +1692,8 @@ service ManagementService {
 
     // Create Secret for Machine User
     //
+    // Deprecated: use [user service v2 AddSecret](apis/resources/user_service_v2/user-service-add-secret.api.mdx) instead.
+    //
     // Create a new secret for a machine user/service account. It is used to authenticate the user (client credential grant).
     rpc GenerateMachineSecret(GenerateMachineSecretRequest) returns (GenerateMachineSecretResponse) {
         option (google.api.http) = {
@@ -1692,6 +1706,7 @@ service ManagementService {
         };
 
         option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
+            deprecated: true;
             tags: "Users";
             tags: "User Machine";
             responses: {
@@ -1713,6 +1728,8 @@ service ManagementService {
 
     // Delete Secret of Machine User
     //
+    // Deprecated: use [user service v2 RemoveSecret](apis/resources/user_service_v2/user-service-remove-secret.api.mdx) instead.
+    //
     // Delete a secret of a machine user/service account. The user will not be able to authenticate with the secret afterward.
     rpc RemoveMachineSecret(RemoveMachineSecretRequest) returns (RemoveMachineSecretResponse) {
         option (google.api.http) = {
@@ -1724,6 +1741,7 @@ service ManagementService {
         };
 
         option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
+            deprecated: true;
             tags: "Users";
             tags: "User Machine";
             responses: {
@@ -1745,6 +1763,8 @@ service ManagementService {
 
     // Get Machine user Key By ID
     //
+    // Deprecated: use [user service v2 ListKeys](apis/resources/user_service_v2/user-service-list-keys.api.mdx) instead.
+    //
     // Get a specific Key of a machine user by its id. Machine keys are used to authenticate with jwt profile authentication.
     rpc GetMachineKeyByIDs(GetMachineKeyByIDsRequest) returns (GetMachineKeyByIDsResponse) {
         option (google.api.http) = {
@@ -1756,6 +1776,7 @@ service ManagementService {
         };
 
         option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
+            deprecated: true;
             tags: "Users";
             tags: "User Machine";
             responses: {
@@ -1775,7 +1796,9 @@ service ManagementService {
         };
     }
 
-    // List Machine Keys
+    // Get Machine user Key By ID
+    //
+    // Deprecated: use [user service v2 ListKeys](apis/resources/user_service_v2/user-service-list-keys.api.mdx) instead.
     //
     // Get the list of keys of a machine user. Machine keys are used to authenticate with jwt profile authentication.
     rpc ListMachineKeys(ListMachineKeysRequest) returns (ListMachineKeysResponse) {
@@ -1789,6 +1812,7 @@ service ManagementService {
         };
 
         option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
+            deprecated: true;
             tags: "Users";
             tags: "User Machine";
             responses: {
@@ -1810,6 +1834,8 @@ service ManagementService {
 
     // Create Key for machine user
     //
+    // Deprecated: use [user service v2 AddKey](apis/resources/user_service_v2/user-service-add-key.api.mdx) instead.
+    //
     // If a public key is not supplied, a new key is generated and will be returned in the response.
     // Make sure to store the returned key.
     // If an RSA public key is supplied, the private key is omitted from the response.
@@ -1825,6 +1851,7 @@ service ManagementService {
         };
 
         option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
+            deprecated: true;
             tags: "Users";
             tags: "User Machine";
             responses: {
@@ -1846,6 +1873,8 @@ service ManagementService {
 
     // Delete Key for machine user
     //
+    // Deprecated: use [user service v2 RemoveKey](apis/resources/user_service_v2/user-service-remove-key.api.mdx) instead.
+    //
     // Delete a specific key from a user.
     // The user will not be able to authenticate with that key afterward.
     rpc RemoveMachineKey(RemoveMachineKeyRequest) returns (RemoveMachineKeyResponse) {
@@ -1858,6 +1887,7 @@ service ManagementService {
         };
 
         option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
+            deprecated: true;
             tags: "Users";
             tags: "User Machine";
             responses: {
@@ -1879,6 +1909,8 @@ service ManagementService {
 
     // Get Personal-Access-Token (PAT) by ID
     //
+    // Deprecated: use [user service v2 ListPersonalAccessTokens](apis/resources/user_service_v2/user-service-list-personal-access-tokens.api.mdx) instead.
+    //
     // Returns the PAT for a user, currently only available for machine users/service accounts. PATs are ready-to-use tokens and can be sent directly in the authentication header.
     rpc GetPersonalAccessTokenByIDs(GetPersonalAccessTokenByIDsRequest) returns (GetPersonalAccessTokenByIDsResponse) {
         option (google.api.http) = {
@@ -1890,6 +1922,7 @@ service ManagementService {
         };
 
         option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
+            deprecated: true;
             tags: "Users";
             tags: "User Machine";
             responses: {
@@ -1911,6 +1944,8 @@ service ManagementService {
 
     // List Personal-Access-Tokens (PATs)
     //
+    // Deprecated: use [user service v2 ListPersonalAccessTokens](apis/resources/user_service_v2/user-service-list-personal-access-tokens.api.mdx) instead.
+    //
     // Returns a list of PATs for a user, currently only available for machine users/service accounts. PATs are ready-to-use tokens and can be sent directly in the authentication header.
     rpc ListPersonalAccessTokens(ListPersonalAccessTokensRequest) returns (ListPersonalAccessTokensResponse) {
         option (google.api.http) = {
@@ -1923,6 +1958,7 @@ service ManagementService {
         };
 
         option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
+            deprecated: true;
             tags: "Users";
             tags: "User Machine";
             responses: {
@@ -1944,6 +1980,8 @@ service ManagementService {
 
     // Create a Personal-Access-Token (PAT)
     //
+    // Deprecated: use [user service v2 AddPersonalAccessToken](apis/resources/user_service_v2/user-service-add-personal-access-token.api.mdx) instead.
+    //
     // Generates a new PAT for the user. Currently only available for machine users.
     // The token will be returned in the response, make sure to store it.
     // PATs are ready-to-use tokens and can be sent directly in the authentication header.
@@ -1958,6 +1996,7 @@ service ManagementService {
         };
 
         option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
+            deprecated: true;
             tags: "Users";
             tags: "User Machine";
             responses: {
@@ -1979,6 +2018,8 @@ service ManagementService {
 
     // Remove a Personal-Access-Token (PAT) by ID
     //
+    // Deprecated: use [user service v2 RemovePersonalAccessToken](apis/resources/user_service_v2/user-service-remove-personal-access-token.api.mdx) instead.
+    //
     // Delete a PAT from a user. Afterward, the user will not be able to authenticate with that token anymore.
     rpc RemovePersonalAccessToken(RemovePersonalAccessTokenRequest) returns (RemovePersonalAccessTokenResponse) {
         option (google.api.http) = {
@@ -1990,6 +2031,7 @@ service ManagementService {
         };
 
         option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
+            deprecated: true;
             tags: "Users";
             tags: "User Machine";
             responses: {

proto/zitadel/user/v2/user_service.proto

@@ -133,6 +133,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"
@@ -162,6 +169,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) = {
@@ -180,6 +189,7 @@ service UserService {
     };
 
     option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
+      deprecated: true;
       responses: {
         key: "200"
         value: {
@@ -260,6 +270,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) = {
@@ -274,6 +286,7 @@ service UserService {
     };
 
     option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
+      deprecated: true;
       responses: {
         key: "200"
         value: {
@@ -380,6 +393,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) = {
@@ -394,6 +409,7 @@ service UserService {
     };
 
     option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
+      deprecated: true;
       responses: {
         key: "200"
         value: {
@@ -411,6 +427,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) = {
@@ -425,6 +443,7 @@ service UserService {
     };
 
     option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
+      deprecated: true;
       responses: {
         key: "200"
         value: {
@@ -500,6 +519,7 @@ service UserService {
     };
   }
 
+
   // Update a User
   //
   // Partially update an existing user.
@@ -509,6 +529,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: {
@@ -550,6 +574,8 @@ service UserService {
 
   // Update Human 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) = {
@@ -564,6 +590,7 @@ service UserService {
     };
 
     option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
+      deprecated: true;
       responses: {
         key: "200"
         value: {
@@ -1351,6 +1378,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) = {
@@ -1365,6 +1394,7 @@ service UserService {
     };
 
     option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
+      deprecated: true;
       responses: {
         key: "200"
         value: {
@@ -1380,245 +1410,6 @@ service UserService {
     };
   }
 
-
-  // Add a Users Secret
-  //
-  // Generates a client secret for the user.
-  // The client id is the users username.
-  // If the user already has a secret, it is overwritten.
-  // Only users of type machine can have a secret.
-  //
-  // Required permission:
-  //   - user.write
-  rpc AddSecret(AddSecretRequest) returns (AddSecretResponse) {
-    option (zitadel.protoc_gen_zitadel.v2.options) = {
-      auth_option: {
-        permission: "authenticated"
-      }
-    };
-
-    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
-      responses: {
-        key: "200"
-        value: {
-          description: "The secret was successfully generated.";
-        }
-      };
-      responses: {
-        key: "404"
-        value: {
-          description: "The user ID does not exist.";
-          schema: {
-            json_schema: {
-              ref: "#/definitions/rpcStatus";
-            };
-          };
-        }
-      };
-    };
-  }
-
-  // Remove a Users Secret
-  //
-  // Remove the current client ID and client secret from a machine user.
-  //
-  // Required permission:
-  //   - user.write
-  rpc RemoveSecret(RemoveSecretRequest) returns (RemoveSecretResponse) {
-    option (zitadel.protoc_gen_zitadel.v2.options) = {
-      auth_option: {
-        permission: "authenticated"
-      }
-    };
-
-    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
-      responses: {
-        key: "200"
-        value: {
-          description: "The secret was either successfully removed or it didn't exist in the first place.";
-        }
-      };
-    };
-  }
-
-  // Add a Key
-  //
-  // Add a keys that can be used to securely authenticate at the Zitadel APIs using JWT profile authentication using short-lived tokens.
-  // Make sure you store the returned key safely, as you won't be able to read it from the Zitadel API anymore.
-  // Only users of type machine can have keys.
-  //
-  // Required permission:
-  //   - user.write
-  rpc AddKey(AddKeyRequest) returns (AddKeyResponse) {
-    option (zitadel.protoc_gen_zitadel.v2.options) = {
-      auth_option: {
-        permission: "authenticated"
-      }
-    };
-
-    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
-      responses: {
-        key: "200"
-        value: {
-          description: "The key was successfully created.";
-        }
-      };
-      responses: {
-        key: "404"
-        value: {
-          description: "The user ID does not exist.";
-          schema: {
-            json_schema: {
-              ref: "#/definitions/rpcStatus";
-            };
-          };
-        }
-      };
-    };
-  }
-
-  // Remove a Key
-  //
-  // Remove a machine users key by the given key ID and an optionally given user ID.
-  //
-  // Required permission:
-  //   - user.write
-  rpc RemoveKey(RemoveKeyRequest) returns (RemoveKeyResponse) {
-    option (zitadel.protoc_gen_zitadel.v2.options) = {
-      auth_option: {
-        permission: "authenticated"
-      }
-    };
-
-    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
-      responses: {
-        key: "200"
-        value: {
-          description: "The key was either successfully removed or it not found in the first place.";
-        }
-      };
-    };
-  }
-
-  // Search Keys
-  //
-  // List all matching keys. By default all keys of the instance on which the caller has permission to read the owning users are returned.
-  // Make sure to include a limit and sorting for pagination.
-  //
-  // Required permission:
-  //   - user.read
-  rpc ListKeys(ListKeysRequest) returns (ListKeysResponse) {
-    option (zitadel.protoc_gen_zitadel.v2.options) = {
-      auth_option: {
-        permission: "authenticated"
-      }
-    };
-
-    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
-      responses: {
-        key: "200";
-        value: {
-          description: "A list of all machine user keys matching the query";
-        };
-      };
-      responses: {
-        key: "400";
-        value: {
-          description: "invalid list query";
-        };
-      };
-    };
-  }
-
-  // Add a Personal Access Token
-  //
-  // Personal access tokens (PAT) are the easiest way to authenticate to the Zitadel APIs.
-  // Make sure you store the returned PAT safely, as you won't be able to read it from the Zitadel API anymore.
-  // Only users of type machine can have personal access tokens.
-  //
-  // Required permission:
-  //   - user.write
-  rpc AddPersonalAccessToken(AddPersonalAccessTokenRequest) returns (AddPersonalAccessTokenResponse) {
-    option (zitadel.protoc_gen_zitadel.v2.options) = {
-      auth_option: {
-        permission: "authenticated"
-      }
-    };
-
-    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
-      responses: {
-        key: "200"
-        value: {
-          description: "The personal access token was successfully created.";
-        }
-      };
-      responses: {
-        key: "404"
-        value: {
-          description: "The user ID does not exist.";
-          schema: {
-            json_schema: {
-              ref: "#/definitions/rpcStatus";
-            };
-          };
-        }
-      };
-    };
-  }
-
-  // Remove a Personal Access Token
-  //
-  // Removes a machine users personal access token by the given token ID and an optionally given user ID.
-  //
-  // Required permission:
-  //   - user.write
-  rpc RemovePersonalAccessToken(RemovePersonalAccessTokenRequest) returns (RemovePersonalAccessTokenResponse) {
-    option (zitadel.protoc_gen_zitadel.v2.options) = {
-      auth_option: {
-        permission: "authenticated"
-      }
-    };
-
-    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
-      responses: {
-        key: "200"
-        value: {
-          description: "The personal access token was either successfully removed or it was not found in the first place.";
-        }
-      };
-    };
-  }
-
-  // Search Personal Access Tokens
-  //
-  // List all personal access tokens. By default all personal access tokens of the instance on which the caller has permission to read the owning users are returned.
-  // Make sure to include a limit and sorting for pagination.
-  //
-  // Required permission:
-  //   - user.read
-  rpc ListPersonalAccessTokens(ListPersonalAccessTokensRequest) returns (ListPersonalAccessTokensResponse) {
-    option (zitadel.protoc_gen_zitadel.v2.options) = {
-      auth_option: {
-        permission: "authenticated"
-      }
-    };
-
-    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
-      responses: {
-        key: "200";
-        value: {
-          description: "A list of all personal access tokens matching the query";
-        };
-      };
-      responses: {
-        key: "400";
-        value: {
-          description: "invalid list query";
-        };
-      };
-    };
-  }
-
   // List all possible authentication methods of a user
   //
   // List all possible authentication methods of a user like password, passwordless, (T)OTP and more..
@@ -1793,6 +1584,281 @@ service UserService {
       }
     };
   }
+
+  // Add a Users Secret
+  //
+  // Generates a client secret for the user.
+  // The client id is the users username.
+  // If the user already has a secret, it is overwritten.
+  // Only users of type machine can have a secret.
+  //
+  // 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"
+      }
+    };
+
+    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
+      responses: {
+        key: "200"
+        value: {
+          description: "The secret was successfully generated.";
+        }
+      };
+      responses: {
+        key: "404"
+        value: {
+          description: "The user ID does not exist.";
+          schema: {
+            json_schema: {
+              ref: "#/definitions/rpcStatus";
+            };
+          };
+        }
+      };
+    };
+  }
+
+  // Remove a Users Secret
+  //
+  // Remove the current client ID and client secret from a machine user.
+  //
+  // 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"
+      }
+    };
+
+    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
+      responses: {
+        key: "200"
+        value: {
+          description: "The secret was either successfully removed or it didn't exist in the first place.";
+        }
+      };
+    };
+  }
+
+  // Add a Key
+  //
+  // Add a keys that can be used to securely authenticate at the Zitadel APIs using JWT profile authentication using short-lived tokens.
+  // Make sure you store the returned key safely, as you won't be able to read it from the Zitadel API anymore.
+  // Only users of type machine can have keys.
+  //
+  // 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"
+      }
+    };
+
+    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
+      responses: {
+        key: "200"
+        value: {
+          description: "The key was successfully created.";
+        }
+      };
+      responses: {
+        key: "404"
+        value: {
+          description: "The user ID does not exist.";
+          schema: {
+            json_schema: {
+              ref: "#/definitions/rpcStatus";
+            };
+          };
+        }
+      };
+    };
+  }
+
+  // Remove a Key
+  //
+  // Remove a machine users key by the given key ID and an optionally given user ID.
+  //
+  // 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"
+      }
+    };
+
+    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
+      responses: {
+        key: "200"
+        value: {
+          description: "The key was either successfully removed or it not found in the first place.";
+        }
+      };
+    };
+  }
+
+  // Search Keys
+  //
+  // List all matching keys. By default all keys of the instance on which the caller has permission to read the owning users are returned.
+  // Make sure to include a limit and sorting for pagination.
+  //
+  // 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"
+      }
+    };
+
+    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
+      responses: {
+        key: "200";
+        value: {
+          description: "A list of all machine user keys matching the query";
+        };
+      };
+      responses: {
+        key: "400";
+        value: {
+          description: "invalid list query";
+        };
+      };
+    };
+  }
+
+  // Add a Personal Access Token
+  //
+  // Personal access tokens (PAT) are the easiest way to authenticate to the Zitadel APIs.
+  // Make sure you store the returned PAT safely, as you won't be able to read it from the Zitadel API anymore.
+  // Only users of type machine can have personal access tokens.
+  //
+  // 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"
+      }
+    };
+
+    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
+      responses: {
+        key: "200"
+        value: {
+          description: "The personal access token was successfully created.";
+        }
+      };
+      responses: {
+        key: "404"
+        value: {
+          description: "The user ID does not exist.";
+          schema: {
+            json_schema: {
+              ref: "#/definitions/rpcStatus";
+            };
+          };
+        }
+      };
+    };
+  }
+
+  // Remove a Personal Access Token
+  //
+  // Removes a machine users personal access token by the given token ID and an optionally given user ID.
+  //
+  // 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"
+      }
+    };
+
+    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
+      responses: {
+        key: "200"
+        value: {
+          description: "The personal access token was either successfully removed or it was not found in the first place.";
+        }
+      };
+    };
+  }
+
+  // Search Personal Access Tokens
+  //
+  // List all personal access tokens. By default all personal access tokens of the instance on which the caller has permission to read the owning users are returned.
+  // Make sure to include a limit and sorting for pagination.
+  //
+  // 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"
+      }
+    };
+
+    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
+      responses: {
+        key: "200";
+        value: {
+          description: "A list of all personal access tokens matching the query";
+        };
+      };
+      responses: {
+        key: "400";
+        value: {
+          description: "invalid list query";
+        };
+      };
+    };
+  }
 }
 
 message AddHumanUserRequest{