From 5da5ccda5ced787f28addbc88f087082e2fd1a39 Mon Sep 17 00:00:00 2001 From: Stefan Benz <46600784+stebenz@users.noreply.github.com> Date: Wed, 25 Jun 2025 16:53:40 +0200 Subject: [PATCH] fix: correct user v2 api docs for v3 (#10112) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit # 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 Remove the unnecessary changes in the documentation for now, and create a second PR which can then be used to update the documentation. # Additional Changes Correct integration tests which also use the endpoints. # Additional Context Closes #10083 --------- Co-authored-by: Fabienne Bühler --- proto/zitadel/management.proto | 44 +- proto/zitadel/user/v2/user_service.proto | 544 ++++++++++------------- 2 files changed, 240 insertions(+), 348 deletions(-) diff --git a/proto/zitadel/management.proto b/proto/zitadel/management.proto index 8cd0b22759..d633fbe8c5 100644 --- a/proto/zitadel/management.proto +++ b/proto/zitadel/management.proto @@ -493,8 +493,6 @@ 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) = { @@ -507,7 +505,6 @@ service ManagementService { }; option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = { - deprecated: true; tags: "Users"; tags: "User Machine"; responses: { @@ -693,8 +690,6 @@ 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) = { @@ -708,7 +703,6 @@ service ManagementService { option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = { tags: "Users"; - deprecated: true; responses: { key: "200" value: { @@ -1124,8 +1118,6 @@ 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) = { @@ -1140,7 +1132,6 @@ service ManagementService { option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = { tags: "Users"; tags: "User Human"; - deprecated: true; responses: { key: "200" value: { @@ -1656,8 +1647,6 @@ 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) = { @@ -1670,7 +1659,6 @@ service ManagementService { }; option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = { - deprecated: true; tags: "Users"; tags: "User Machine"; responses: { @@ -1692,8 +1680,6 @@ 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) = { @@ -1706,7 +1692,6 @@ service ManagementService { }; option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = { - deprecated: true; tags: "Users"; tags: "User Machine"; responses: { @@ -1728,8 +1713,6 @@ 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) = { @@ -1741,7 +1724,6 @@ service ManagementService { }; option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = { - deprecated: true; tags: "Users"; tags: "User Machine"; responses: { @@ -1763,8 +1745,6 @@ 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) = { @@ -1776,7 +1756,6 @@ service ManagementService { }; option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = { - deprecated: true; tags: "Users"; tags: "User Machine"; responses: { @@ -1796,9 +1775,7 @@ 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. + // List Machine Keys // // Get the list of keys of a machine user. Machine keys are used to authenticate with jwt profile authentication. rpc ListMachineKeys(ListMachineKeysRequest) returns (ListMachineKeysResponse) { @@ -1812,7 +1789,6 @@ service ManagementService { }; option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = { - deprecated: true; tags: "Users"; tags: "User Machine"; responses: { @@ -1834,8 +1810,6 @@ 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. @@ -1851,7 +1825,6 @@ service ManagementService { }; option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = { - deprecated: true; tags: "Users"; tags: "User Machine"; responses: { @@ -1873,8 +1846,6 @@ 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) { @@ -1887,7 +1858,6 @@ service ManagementService { }; option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = { - deprecated: true; tags: "Users"; tags: "User Machine"; responses: { @@ -1909,8 +1879,6 @@ 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) = { @@ -1922,7 +1890,6 @@ service ManagementService { }; option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = { - deprecated: true; tags: "Users"; tags: "User Machine"; responses: { @@ -1944,8 +1911,6 @@ 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) = { @@ -1958,7 +1923,6 @@ service ManagementService { }; option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = { - deprecated: true; tags: "Users"; tags: "User Machine"; responses: { @@ -1980,8 +1944,6 @@ 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. @@ -1996,7 +1958,6 @@ service ManagementService { }; option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = { - deprecated: true; tags: "Users"; tags: "User Machine"; responses: { @@ -2018,8 +1979,6 @@ 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) = { @@ -2031,7 +1990,6 @@ service ManagementService { }; option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = { - deprecated: true; tags: "Users"; tags: "User Machine"; responses: { diff --git a/proto/zitadel/user/v2/user_service.proto b/proto/zitadel/user/v2/user_service.proto index a416555905..79f66266bc 100644 --- a/proto/zitadel/user/v2/user_service.proto +++ b/proto/zitadel/user/v2/user_service.proto @@ -133,13 +133,6 @@ 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" @@ -169,8 +162,6 @@ 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) = { @@ -189,7 +180,6 @@ service UserService { }; option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = { - deprecated: true; responses: { key: "200" value: { @@ -270,8 +260,6 @@ 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) = { @@ -286,7 +274,6 @@ service UserService { }; option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = { - deprecated: true; responses: { key: "200" value: { @@ -393,8 +380,6 @@ 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) = { @@ -409,7 +394,6 @@ service UserService { }; option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = { - deprecated: true; responses: { key: "200" value: { @@ -427,8 +411,6 @@ 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) = { @@ -443,7 +425,6 @@ service UserService { }; option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = { - deprecated: true; responses: { key: "200" value: { @@ -519,7 +500,6 @@ service UserService { }; } - // Update a User // // Partially update an existing user. @@ -529,10 +509,6 @@ 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: { @@ -574,8 +550,6 @@ 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) = { @@ -590,7 +564,6 @@ service UserService { }; option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = { - deprecated: true; responses: { key: "200" value: { @@ -1378,8 +1351,6 @@ 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) = { @@ -1394,7 +1365,6 @@ service UserService { }; option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = { - deprecated: true; responses: { key: "200" value: { @@ -1410,6 +1380,245 @@ 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.. @@ -1584,281 +1793,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 (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{