fix(api): deprecate v2beta endpoints of existing v2 services (#10841)

# Which Problems Are Solved

As part of our efforts to simplify the structure and versions of our
APIs, were moving all existing v2beta endpoints to v2 and deprecate
them. They will be removed in Zitadel V5.

# How the Problems Are Solved

- This PR deprecates all v2beta service and their endpoints, which have
already a corresponding v2 version and should not be used anymore.
- The comments and have been improved and, where not already done, moved
from swagger annotations to proto.
- All required fields have been marked with `(google.api.field_behavior)
= REQUIRED` and validation rules have been added where missing.
- Removed the "required flag" comments on the Action and WebKey service
endpoints, since they were removed in Zitadel v4.
- The `SetSession` endpoint already documented that the token does not
have to be provided anymore and will be ignored if still sent, but it
was actually still checked if provided. The corresponding check has been
removed and the field is now properly deprecated in the proto as well.

# Additional Changes

None

# Additional Context

- part of #10772
- requires backport to v4.x

(cherry picked from commit e25b21a6a4)

internal/api/grpc/session/v2/session.go

@@ -51,7 +51,7 @@ func (s *Server) SetSession(ctx context.Context, req *connect.Request[session.Se
 		return nil, err
 	}
 
-	set, err := s.command.UpdateSession(ctx, req.Msg.GetSessionId(), req.Msg.GetSessionToken(), cmds, req.Msg.GetMetadata(), req.Msg.GetLifetime().AsDuration())
+	set, err := s.command.UpdateSession(ctx, req.Msg.GetSessionId(), cmds, req.Msg.GetMetadata(), req.Msg.GetLifetime().AsDuration())
 	if err != nil {
 		return nil, err
 	}

internal/api/grpc/session/v2beta/session.go

@@ -89,7 +89,7 @@ func (s *Server) SetSession(ctx context.Context, req *connect.Request[session.Se
 		return nil, err
 	}
 
-	set, err := s.command.UpdateSession(ctx, req.Msg.GetSessionId(), req.Msg.GetSessionToken(), cmds, req.Msg.GetMetadata(), req.Msg.GetLifetime().AsDuration())
+	set, err := s.command.UpdateSession(ctx, req.Msg.GetSessionId(), cmds, req.Msg.GetMetadata(), req.Msg.GetLifetime().AsDuration())
 	if err != nil {
 		return nil, err
 	}

internal/command/session.go

@@ -301,7 +301,7 @@ func (c *Commands) CreateSession(
 	if err != nil {
 		return nil, err
 	}
-	if err = c.checkSessionWritePermission(ctx, sessionWriteModel, ""); err != nil {
+	if err = c.checkSessionWritePermission(ctx, sessionWriteModel); err != nil {
 		return nil, err
 	}
 	cmd := c.NewSessionCommands(cmds, sessionWriteModel)
@@ -311,7 +311,7 @@ func (c *Commands) CreateSession(
 
 func (c *Commands) UpdateSession(
 	ctx context.Context,
-	sessionID, sessionToken string,
+	sessionID string,
 	cmds []SessionCommand,
 	metadata map[string][]byte,
 	lifetime time.Duration,
@@ -321,7 +321,7 @@ func (c *Commands) UpdateSession(
 	if err != nil {
 		return nil, err
 	}
-	if err = c.checkSessionWritePermission(ctx, sessionWriteModel, sessionToken); err != nil {
+	if err = c.checkSessionWritePermission(ctx, sessionWriteModel); err != nil {
 		return nil, err
 	}
 	cmd := c.NewSessionCommands(cmds, sessionWriteModel)
@@ -400,14 +400,10 @@ func (c *Commands) updateSession(ctx context.Context, checks *SessionCommands, m
 	return changed, nil
 }
 
-// checkSessionWritePermission will check that the provided sessionToken is correct or
+// checkSessionWritePermission will check that the caller is granted the "session.write" permission on the resource owner of the authenticated user.
-// if empty, check that the caller is granted the "session.write" permission on the resource owner of the authenticated user.
+// In case the user is not set, and the userResourceOwner is not set (also the case for the session creation),
-// In case the user is not set and the userResourceOwner is not set (also the case for the session creation),
 // it will check permission on the instance.
-func (c *Commands) checkSessionWritePermission(ctx context.Context, model *SessionWriteModel, sessionToken string) error {
+func (c *Commands) checkSessionWritePermission(ctx context.Context, model *SessionWriteModel) error {
-	if sessionToken != "" {
-		return c.sessionTokenVerifier(ctx, sessionToken, model.AggregateID, model.TokenID)
-	}
 	userResourceOwner, err := c.sessionUserResourceOwner(ctx, model)
 	if err != nil {
 		return err

internal/command/session_test.go

@@ -306,16 +306,14 @@ func TestCommands_CreateSession(t *testing.T) {
 func TestCommands_UpdateSession(t *testing.T) {
 	type fields struct {
 		eventstore      func(*testing.T) *eventstore.Eventstore
-		tokenVerifier   func(ctx context.Context, sessionToken, sessionID, tokenID string) (err error)
 		checkPermission domain.PermissionCheck
 	}
 	type args struct {
-		ctx          context.Context
+		ctx       context.Context
-		sessionID    string
+		sessionID string
-		sessionToken string
+		checks    []SessionCommand
-		checks       []SessionCommand
+		metadata  map[string][]byte
-		metadata     map[string][]byte
+		lifetime  time.Duration
-		lifetime     time.Duration
 	}
 	type res struct {
 		want *SessionChanged
@@ -341,37 +339,6 @@ func TestCommands_UpdateSession(t *testing.T) {
 				err: zerrors.ThrowInternal(nil, "id", "filter failed"),
 			},
 		},
-		{
-			"invalid session token",
-			fields{
-				eventstore: expectEventstore(
-					expectFilter(
-						eventFromEventPusher(
-							session.NewAddedEvent(context.Background(),
-								&session.NewAggregate("sessionID", "instance1").Aggregate,
-								&domain.UserAgent{
-									FingerprintID: gu.Ptr("fp1"),
-									IP:            net.ParseIP("1.2.3.4"),
-									Description:   gu.Ptr("firefox"),
-									Header:        http.Header{"foo": []string{"bar"}},
-								},
-							)),
-						eventFromEventPusher(
-							session.NewTokenSetEvent(context.Background(), &session.NewAggregate("sessionID", "instance1").Aggregate,
-								"tokenID")),
-					),
-				),
-				tokenVerifier: newMockTokenVerifierInvalid(),
-			},
-			args{
-				ctx:          context.Background(),
-				sessionID:    "sessionID",
-				sessionToken: "invalid",
-			},
-			res{
-				err: zerrors.ThrowPermissionDenied(nil, "COMMAND-sGr42", "Errors.Session.Token.Invalid"),
-			},
-		},
 		{
 			"no token, no permission",
 			fields{
@@ -422,14 +389,11 @@ func TestCommands_UpdateSession(t *testing.T) {
 								"tokenID")),
 					),
 				),
-				tokenVerifier: func(ctx context.Context, sessionToken, sessionID, tokenID string) (err error) {
+				checkPermission: newMockPermissionCheckAllowed(),
-					return nil
-				},
 			},
 			args{
-				ctx:          context.Background(),
+				ctx:       context.Background(),
-				sessionID:    "sessionID",
+				sessionID: "sessionID",
-				sessionToken: "token",
 			},
 			res{
 				want: &SessionChanged{
@@ -446,11 +410,10 @@ func TestCommands_UpdateSession(t *testing.T) {
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
 			c := &Commands{
-				eventstore:           tt.fields.eventstore(t),
+				eventstore:      tt.fields.eventstore(t),
-				sessionTokenVerifier: tt.fields.tokenVerifier,
+				checkPermission: tt.fields.checkPermission,
-				checkPermission:      tt.fields.checkPermission,
 			}
-			got, err := c.UpdateSession(tt.args.ctx, tt.args.sessionID, tt.args.sessionToken, tt.args.checks, tt.args.metadata, tt.args.lifetime)
+			got, err := c.UpdateSession(tt.args.ctx, tt.args.sessionID, tt.args.checks, tt.args.metadata, tt.args.lifetime)
 			require.ErrorIs(t, err, tt.res.err)
 			assert.Equal(t, tt.res.want, got)
 		})

proto/zitadel/action/v2/action_service.proto

@@ -117,9 +117,6 @@ service ActionService {
   //
   // Required permission:
   //   - `action.target.write`
-  //
-  // Required feature flag:
-  //   - `actions`
   rpc CreateTarget (CreateTargetRequest) returns (CreateTargetResponse) {
     option (google.api.http) = {
       post: "/v2/actions/targets"
@@ -161,9 +158,6 @@ service ActionService {
   //
   // Required permission:
   //   - `action.target.write`
-  //
-  // Required feature flag:
-  //   - `actions`
   rpc UpdateTarget (UpdateTargetRequest) returns (UpdateTargetResponse) {
     option (google.api.http) = {
       post: "/v2/actions/targets/{id}"
@@ -206,9 +200,6 @@ service ActionService {
   //
   // Required permission:
   //   - `action.target.delete`
-  //
-  // Required feature flag:
-  //   - `actions`
   rpc DeleteTarget (DeleteTargetRequest) returns (DeleteTargetResponse) {
     option (google.api.http) = {
       delete: "/v2/actions/targets/{id}"
@@ -242,9 +233,6 @@ service ActionService {
   //
   // Required permission:
   //   - `action.target.read`
-  //
-  // Required feature flag:
-  //   - `actions`
   rpc GetTarget (GetTargetRequest) returns (GetTargetResponse) {
     option (google.api.http) = {
       get: "/v2/actions/targets/{id}"
@@ -285,9 +273,6 @@ service ActionService {
   //
   // Required permission:
   //   - `action.target.read`
-  //
-  // Required feature flag:
-  //   - `actions`
   rpc ListTargets (ListTargetsRequest) returns (ListTargetsResponse) {
     option (google.api.http) = {
       post: "/v2/actions/targets/search",
@@ -329,9 +314,6 @@ service ActionService {
   //
   // Required permission:
   //   - `action.execution.write`
-  //
-  // Required feature flag:
-  //   - `actions`
   rpc SetExecution (SetExecutionRequest) returns (SetExecutionResponse) {
     option (google.api.http) = {
       put: "/v2/actions/executions"
@@ -367,9 +349,6 @@ service ActionService {
   //
   // Required permission:
   //   - `action.execution.read`
-  //
-  // Required feature flag:
-  //   - `actions`
   rpc ListExecutions (ListExecutionsRequest) returns (ListExecutionsResponse) {
     option (google.api.http) = {
       post: "/v2/actions/executions/search"
@@ -474,38 +453,63 @@ service ActionService {
 message CreateTargetRequest {
   string name = 1 [
     (validate.rules).string = {min_len: 1, max_len: 1000},
+    (google.api.field_behavior) = REQUIRED,
     (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
       example: "\"ip_allow_list\"";
       min_length: 1
       max_length: 1000
     }
   ];
+
   // Defines the target type and how the response of the target is treated.
   oneof target_type {
     option (validate.required) = true;
-    // Wait for response but response body is ignored, status is checked, call is sent as post.
+
+    // The HTTP call to this target will be a POST request.
+    // The response of the target will only be checked for the status code.
+    // The returned body will be ignored.
+    // In case of an error status code (non 2xx) and interrupt_on_error is set to true,
+    // the execution will be aborted and no further targets will be called.
     RESTWebhook rest_webhook = 2;
-    // Wait for response and response body is used, status is checked, call is sent as post.
+
+    // The HTTP call to this target will be a POST request.
+    // The response of the target will be checked for the status code and the body.
+    // In case of an error status code (non 2xx) and interrupt_on_error is set to true,
+    // the execution will be aborted and no further targets will be called.
+    // In case of a successful status code (2xx) the body will be parsed and mapped.
+    // This allows to modify the payload of request and response executions.
     RESTCall rest_call = 3;
-    // Call is executed in parallel to others, ZITADEL does not wait until the call is finished. The state is ignored, call is sent as post.
+
+    // The HTTP call to this target will be a POST request.
+    // The call is sent asynchronously and ZITADEL does not wait for the response.
+    // The response of the target is ignored, no status or body is checked.
+    // This is typically used for executions of type "events".
     RESTAsync rest_async = 4;
   }
+
   // Timeout defines the duration until ZITADEL cancels the execution.
-  // If the target doesn't respond before this timeout expires, then the connection is closed and the action fails. Depending on the target type and possible setting on `interrupt_on_error` following targets will not be called. In case of a `rest_async` target only this specific target will fail, without any influence on other targets of the same execution.
+  // If the target doesn't respond before this timeout expires, then the connection is closed and the action fails.
+  // Depending on the target type and possible setting on `interrupt_on_error` following targets will not be called.
+  // In case of a `rest_async` target only this specific target will fail, without any influence on other targets of the same execution.
+  // The maximum timeout is 270 seconds or 4.5 minutes.
   google.protobuf.Duration timeout = 5 [
     (validate.rules).duration = {gte: {}, lte: {seconds: 270}},
     (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
       example: "\"10s\"";
     }
   ];
+
+  // The URL of the endpoint to call.
   string endpoint = 6 [
-    (validate.rules).string = {min_len: 1, max_len: 1000},
+    (validate.rules).string = {min_len: 1, max_len: 2048},
+    (google.api.field_behavior) = REQUIRED,
     (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
       example: "\"https://example.com/hooks/ip_check\""
       min_length: 1
-      max_length: 1000
+      max_length: 2048
     }
   ];
+
   option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_schema) = {
     example: "{\"name\": \"ip_allow_list\",\"restWebhook\":{\"interruptOnError\":true},\"timeout\":\"10s\",\"endpoint\":\"https://example.com/hooks/ip_check\"}";
   };
@@ -518,13 +522,19 @@ message CreateTargetResponse {
       example: "\"69629012906488334\"";
     }
   ];
+
   // The timestamp of the target creation.
   google.protobuf.Timestamp creation_date = 2 [
     (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
       example: "\"2024-12-18T07:50:47.492Z\"";
     }
   ];
+
   // Key used to sign and check payload sent to the target.
+  // The key can be used to verify the integrity and authenticity of the request
+  // on the receiver side. The key should be treated as a secret and only known to ZITADEL and the receiver.
+  // The signature is included in the request header `X-ZITADEL-Signature`
+  // and calculated over the raw body of the request using HMAC with SHA256.
   string signing_key = 3 [
     (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
       example: "\"98KmsU67\""
@@ -533,14 +543,19 @@ message CreateTargetResponse {
 }
 
 message UpdateTargetRequest {
+  // The unique identifier of the target to update.
   string id = 1 [
     (validate.rules).string = {min_len: 1, max_len: 200},
+    (google.api.field_behavior) = REQUIRED,
     (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
       min_length: 1,
       max_length: 200,
       example: "\"69629026806489455\"";
     }
   ];
+
+  // Optionally, update the name of the target.
+  // If not set, the name will not be changed.
   optional string name = 2 [
     (validate.rules).string = {min_len: 1, max_len: 1000},
     (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
@@ -549,31 +564,56 @@ message UpdateTargetRequest {
       max_length: 1000
     }
   ];
+
   // Defines the target type and how the response of the target is treated.
   oneof target_type {
-    // Wait for response but response body is ignored, status is checked, call is sent as post.
+
+    // The HTTP call to this target will be a POST request.
+    // The response of the target will only be checked for the status code.
+    // The returned body will be ignored.
+    // In case of an error status code (non 2xx) and interrupt_on_error is set to true,
+    // the execution will be aborted and no further targets will be called.
     RESTWebhook rest_webhook = 3;
-    // Wait for response and response body is used, status is checked, call is sent as post.
+
+    // The HTTP call to this target will be a POST request.
+    // The response of the target will be checked for the status code and the body.
+    // In case of an error status code (non 2xx) and interrupt_on_error is set to true,
+    // the execution will be aborted and no further targets will be called.
+    // In case of a successful status code (2xx) the body will be parsed and mapped.
+    // This allows to modify the payload of request and response executions.
     RESTCall rest_call = 4;
-    // Call is executed in parallel to others, ZITADEL does not wait until the call is finished. The state is ignored, call is sent as post.
+
+    // The HTTP call to this target will be a POST request.
+    // The call is sent asynchronously and ZITADEL does not wait for the response.
+    // The response of the target is ignored, no status or body is checked.
+    // This is typically used for executions of type "events".
     RESTAsync rest_async = 5;
   }
+
   // Timeout defines the duration until ZITADEL cancels the execution.
-  // If the target doesn't respond before this timeout expires, then the connection is closed and the action fails. Depending on the target type and possible setting on `interrupt_on_error` following targets will not be called. In case of a `rest_async` target only this specific target will fail, without any influence on other targets of the same execution.
+  // If the target doesn't respond before this timeout expires, then the connection is closed and the action fails.
+  // Depending on the target type and possible setting on `interrupt_on_error` following targets will not be called.
+  // In case of a `rest_async` target only this specific target will fail, without any influence on other targets of the same execution.
+  // The maximum timeout is 270 seconds or 4.5 minutes.
+  // If not set, the timeout will not be changed.
   optional google.protobuf.Duration timeout = 6 [
     (validate.rules).duration = {gte: {}, lte: {seconds: 270}},
     (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
       example: "\"10s\"";
     }
   ];
+
+  // The new URL of the endpoint to call.
+  // If not set, the endpoint will not be changed.
   optional string endpoint = 7 [
-    (validate.rules).string = {min_len: 1, max_len: 1000},
+    (validate.rules).string = {min_len: 1, max_len: 2048},
     (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
       example: "\"https://example.com/hooks/ip_check\""
       min_length: 1
-      max_length: 1000
+      max_length: 2048
     }
   ];
+
   // Regenerate the key used for signing and checking the payload sent to the target.
   // Set the graceful period for the existing key. During that time, the previous
   // signing key and the new one will be used to sign the request to allow you a smooth
@@ -589,6 +629,7 @@ message UpdateTargetRequest {
       maximum: 0
     }
   ];
+
   option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_schema) = {
     example: "{\"name\": \"ip_allow_list\",\"restCall\":{\"interruptOnError\":true},\"timeout\":\"10s\",\"endpoint\":\"https://example.com/hooks/ip_check\",\"expirationSigningKey\":\"0s\"}";
   };
@@ -601,7 +642,13 @@ message UpdateTargetResponse {
       example: "\"2025-01-23T10:34:18.051Z\"";
     }
   ];
+
   // Key used to sign and check payload sent to the target.
+  // The key can be used to verify the integrity and authenticity of the request
+  // on the receiver side. The key should be treated as a secret and only known to ZITADEL and the receiver.
+  // The signature is included in the request header `X-ZITADEL-Signature`
+  // and calculated over the raw body of the request using HMAC with SHA256.
+  // The key is only returned if expirationSigningKey was set in the request.
   optional string signing_key = 2 [
     (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
       example: "\"98KmsU67\""
@@ -610,6 +657,7 @@ message UpdateTargetResponse {
 }
 
 message DeleteTargetRequest {
+  // The unique identifier of the target to delete.
   string id = 1 [
     (validate.rules).string = {min_len: 1, max_len: 200},
     (google.api.field_behavior) = REQUIRED,
@@ -633,8 +681,10 @@ message DeleteTargetResponse {
 }
 
 message GetTargetRequest {
+  // The unique identifier of the target to retrieve.
   string id = 1 [
     (validate.rules).string = {min_len: 1, max_len: 200},
+    (google.api.field_behavior) = REQUIRED,
     (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
       min_length: 1,
       max_length: 200,
@@ -650,14 +700,17 @@ message GetTargetResponse {
 message ListTargetsRequest {
   // List limitations and ordering.
   optional zitadel.filter.v2.PaginationRequest pagination = 1;
+
   // The field the result is sorted by. The default is the creation date. Beware that if you change this, your result pagination might be inconsistent.
   optional TargetFieldName sorting_column = 2 [
     (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
       default: "\"TARGET_FIELD_NAME_CREATION_DATE\""
     }
   ];
+
   // Define the criteria to query for.
   repeated TargetSearchFilter filters = 3;
+
   option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_schema) = {
     example: "{\"pagination\":{\"offset\":0,\"limit\":0,\"asc\":true},\"sortingColumn\":\"TARGET_FIELD_NAME_CREATION_DATE\",\"filters\":[{\"targetNameFilter\":{\"targetName\":\"ip_allow_list\",\"method\":\"TEXT_FILTER_METHOD_EQUALS\"}},{\"inTargetIdsFilter\":{\"targetIds\":[\"69629023906488334\",\"69622366012355662\"]}}]}";
   };
@@ -665,15 +718,20 @@ message ListTargetsRequest {
 
 message ListTargetsResponse {
   reserved 'result';
+
   zitadel.filter.v2.PaginationResponse pagination = 1;
+
+  // List of all targets matching the query.
   repeated Target targets = 2;
 }
 
 message SetExecutionRequest {
   // Condition defining when the execution should be used.
   Condition condition = 1;
+
   // Ordered list of targets called during the execution.
   repeated string targets = 2;
+
   option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_schema) = {
     example: "{\"condition\":{\"request\":{\"method\":\"zitadel.session.v2.SessionService/ListSessions\"}},\"targets\":[{\"target\":\"69629026806489455\"}]}";
   };
@@ -691,14 +749,18 @@ message SetExecutionResponse {
 message ListExecutionsRequest {
   // List limitations and ordering.
   optional zitadel.filter.v2.PaginationRequest pagination = 1;
-  // The field the result is sorted by. The default is the creation date. Beware that if you change this, your result pagination might be inconsistent.
+
+  // The field the result is sorted by. The default is the creation date.
+  // Beware that if you change this, your result pagination might be inconsistent.
   optional ExecutionFieldName sorting_column = 2 [
     (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
       default: "\"EXECUTION_FIELD_NAME_CREATION_DATE\""
     }
   ];
+
   // Define the criteria to query for.
   repeated ExecutionSearchFilter filters = 3;
+
   option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_schema) = {
     example: "{\"pagination\":{\"offset\":0,\"limit\":0,\"asc\":true},\"sortingColumn\":\"EXECUTION_FIELD_NAME_ID\",\"filters\":[{\"targetFilter\":{\"targetId\":\"69629023906488334\"}}]}";
   };
@@ -706,23 +768,30 @@ message ListExecutionsRequest {
 
 message ListExecutionsResponse {
   reserved 'result';
+
   zitadel.filter.v2.PaginationResponse pagination = 1;
+
+  // List of all executions matching the query.
   repeated Execution executions = 2;
 }
 
 message ListExecutionFunctionsRequest{}
+
 message ListExecutionFunctionsResponse{
-  // All available methods
+  // All available functions to use in conditions.
   repeated string functions = 1;
 }
+
 message ListExecutionMethodsRequest{}
+
 message ListExecutionMethodsResponse{
-  // All available methods
+  // All available methods to use in conditions.
   repeated string methods = 1;
 }
 
 message ListExecutionServicesRequest{}
+
 message ListExecutionServicesResponse{
-  // All available methods
+  // All available services to use in conditions.
   repeated string services = 1;
 }

proto/zitadel/action/v2/execution.proto

@@ -15,20 +15,27 @@ import "google/protobuf/timestamp.proto";
 option go_package = "github.com/zitadel/zitadel/pkg/grpc/action/v2;action";
 
 message Execution {
+  // The condition under which the execution is triggered.
   Condition condition = 1;
+
   // The timestamp of the execution creation.
   google.protobuf.Timestamp creation_date = 2 [
     (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
       example: "\"2024-12-18T07:50:47.492Z\"";
     }
   ];
+
   // The timestamp of the last change to the execution.
   google.protobuf.Timestamp change_date = 3 [
     (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
       example: "\"2025-01-23T10:34:18.051Z\"";
     }
   ];
+
   // Ordered list of targets called during the execution.
+  // The order of the targets in this list defines the order of execution.
+  // If one of the targets fails, depending on the target's type and settings,
+  // the execution might be interrupted and the following targets will not be called.
   repeated string targets = 4;
 }
 
@@ -39,10 +46,13 @@ message Condition {
 
     // Condition-type to execute if a request on the defined API point happens.
     RequestExecution request = 1;
+
     // Condition-type to execute on response if a request on the defined API point happens.
     ResponseExecution response = 2;
+
     // Condition-type to execute if function is used, replaces actions v1.
     FunctionExecution function = 3;
+
     // Condition-type to execute if an event is created in the system.
     EventExecution event = 4;
   }
@@ -52,7 +62,9 @@ message RequestExecution {
   // Condition for the request execution. Only one is possible.
   oneof condition{
     option (validate.required) = true;
-    // GRPC-method as condition.
+
+    // Define a GRPC-method as condition.
+    // When a request to this method happens, the execution is triggered.
     string method = 1 [
       (validate.rules).string = {min_len: 1, max_len: 1000},
       (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
@@ -61,7 +73,9 @@ message RequestExecution {
         example: "\"/zitadel.session.v2.SessionService/ListSessions\"";
       }
     ];
-    // GRPC-service as condition.
+
+    // Define a GRPC-service as condition.
+    // When a request to any method of this service happens, the execution is triggered.
     string service = 2 [
       (validate.rules).string = {min_len: 1, max_len: 1000},
       (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
@@ -70,7 +84,9 @@ message RequestExecution {
         example: "\"zitadel.session.v2.SessionService\"";
       }
     ];
-    // All calls to any available services and methods as condition.
+
+    // Define all calls as condition.
+    // When a call to any available service happens, the execution is triggered.
     bool all = 3 [(validate.rules).bool = {const: true}];
   }
 }
@@ -79,7 +95,9 @@ message ResponseExecution {
   // Condition for the response execution. Only one is possible.
   oneof condition{
     option (validate.required) = true;
-    // GRPC-method as condition.
+
+    // Define a GRPC-method as condition.
+    // Before a response is returned to the client from this method, the execution is triggered.
     string method = 1 [
       (validate.rules).string = {min_len: 1, max_len: 1000},
       (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
@@ -88,7 +106,9 @@ message ResponseExecution {
         example: "\"/zitadel.session.v2.SessionService/ListSessions\"";
       }
     ];
-    // GRPC-service as condition.
+
+    // Define a GRPC-service as condition.
+    // Before a response is returned to the client from any method of this service, the execution is triggered.
     string service = 2 [
       (validate.rules).string = {min_len: 1, max_len: 1000},
       (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
@@ -97,7 +117,10 @@ message ResponseExecution {
         example: "\"zitadel.session.v2.SessionService\"";
       }
     ];
-    // All calls to any available services and methods as condition.
+
+    // Define all calls as condition.
+    // Before a response is returned to the client from any available service,
+    // the execution is triggered.
     bool all = 3 [(validate.rules).bool = {const: true}];
   }
 }
@@ -111,7 +134,9 @@ message EventExecution {
   // Condition for the event execution. Only one is possible.
   oneof condition{
     option (validate.required) = true;
-    // Event name as condition.
+
+    // Define a specific event as condition.
+    // After this event is created, the execution is triggered.
     string event = 1 [
       (validate.rules).string = {min_len: 1, max_len: 1000},
       (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
@@ -120,7 +145,9 @@ message EventExecution {
         example: "\"user.human.added\"";
       }
     ];
-    // Event group as condition, all events under this group.
+
+    // Define an event group as condition.
+    // After any event under this group is created, the execution is triggered.
     string group = 2 [
       (validate.rules).string = {min_len: 1, max_len: 1000},
       (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
@@ -129,7 +156,9 @@ message EventExecution {
         example: "\"user.human\"";
       }
     ];
-    // all events as condition.
+
+    // Define all events as condition.
+    // After any event is created, the execution is triggered.
     bool all = 3 [(validate.rules).bool = {const: true}];
   }
 }

proto/zitadel/action/v2/query.proto

@@ -16,8 +16,13 @@ message ExecutionSearchFilter {
   oneof filter {
     option (validate.required) = true;
 
+    // Filter for executions that are executed when certain conditions are met.
     InConditionsFilter in_conditions_filter = 1;
+
+    // Filter for executions of a certain type.
     ExecutionTypeFilter execution_type_filter = 2;
+
+    // Filter for executions that include a specific target.
     TargetFilter target_filter = 3;
   }
 }
@@ -33,10 +38,9 @@ message ExecutionTypeFilter {
 }
 
 message TargetFilter {
-  // Defines the id to query for.
+  // Defines the id of the target that needs to be part of the execution.
   string target_id = 1 [
     (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
-      description: "the id of the targets to include"
       example: "\"69629023906488334\"";
     }
   ];
@@ -58,7 +62,10 @@ message TargetSearchFilter {
   oneof filter {
     option (validate.required) = true;
 
+    // Filter for targets with a specific name.
     TargetNameFilter target_name_filter = 1;
+
+    // Filter for targets with specific ids.
     InTargetIDsFilter in_target_ids_filter = 2;
   }
 }
@@ -72,12 +79,10 @@ message TargetNameFilter {
       example: "\"ip_allow_list\"";
     }
   ];
+
   // Defines which text comparison method used for the name query.
   zitadel.filter.v2.TextFilterMethod method = 2 [
-    (validate.rules).enum.defined_only = true,
+    (validate.rules).enum.defined_only = true
-    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
-      description: "defines which text equality method is used";
-    }
   ];
 }
 
@@ -85,7 +90,6 @@ message InTargetIDsFilter {
   // Defines the ids to query for.
   repeated string target_ids = 1 [
     (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
-      description: "the ids of the targets to include"
       example: "[\"69629023906488334\",\"69622366012355662\"]";
     }
   ];

proto/zitadel/action/v2/target.proto

@@ -20,29 +20,35 @@ message Target {
       example: "\"69629012906488334\"";
     }
   ];
+
   // The timestamp of the target creation.
   google.protobuf.Timestamp creation_date = 2 [
     (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
       example: "\"2024-12-18T07:50:47.492Z\"";
     }
   ];
-  // The timestamp of the last change to the target (e.g. creation, activation, deactivation).
+
+  // The timestamp of the last change to the target.
   google.protobuf.Timestamp change_date = 3 [
     (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
       example: "\"2025-01-23T10:34:18.051Z\"";
     }
   ];
+
+  // Display name of the target.
   string name = 4 [
     (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
       example: "\"ip_allow_list\"";
     }
   ];
+
   // Defines the target type and how the response of the target is treated.
   oneof target_type {
     RESTWebhook rest_webhook = 5;
     RESTCall rest_call = 6;
     RESTAsync rest_async = 7;
   }
+
   // Timeout defines the duration until ZITADEL cancels the execution.
   // If the target doesn't respond before this timeout expires, the the connection is closed and the action fails. Depending on the target type and possible setting on `interrupt_on_error` following targets will not be called. In case of a `rest_async` target only this specific target will fail, without any influence on other targets of the same execution.
   google.protobuf.Duration timeout = 8 [
@@ -50,11 +56,19 @@ message Target {
       example: "\"10s\"";
     }
   ];
+
+  // The URL that will be called in case of an execution.
   string endpoint = 9 [
     (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
       example: "\"https://example.com/hooks/ip_check\""
     }
   ];
+
+  // The current signing key used to sign the request sent to the target.
+  // The key can be used to verify the integrity and authenticity of the request
+  // on the receiver side. The key should be treated as a secret and only known to ZITADEL and the receiver.
+  // The signature is included in the request header `X-ZITADEL-Signature`
+  // and calculated over the raw body of the request using HMAC with SHA256.
   string signing_key = 10 [
     (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
       example: "\"98KmsU67\""

proto/zitadel/action/v2beta/action_service.proto

@@ -109,17 +109,18 @@ option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_swagger) = {
 
 // Service to manage custom executions.
 // The service provides methods to create, update, delete and list targets and executions.
+//
+// Deprecated: use action service v2 instead. This service will be removed in the next major version of ZITADEL.
 service ActionService {
 
   // Create Target
   //
+  // Deprecated: please move to the corresponding endpoint under action service v2. This endpoint will be removed with the next major version of ZITADEL.
+  //
   // Create a new target to your endpoint, which can be used in executions.
   //
   // Required permission:
   //   - `action.target.write`
-  //
-  // Required feature flag:
-  //   - `actions`
   rpc CreateTarget (CreateTargetRequest) returns (CreateTargetResponse) {
     option (google.api.http) = {
       post: "/v2beta/actions/targets"
@@ -133,6 +134,7 @@ service ActionService {
     };
 
     option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
+      deprecated: true;
       responses: {
         key: "200";
         value: {
@@ -156,14 +158,13 @@ service ActionService {
 
   // Update Target
   //
+  // Deprecated: please move to the corresponding endpoint under action service v2. This endpoint will be removed with the next major version of ZITADEL.
+  //
   // Update an existing target.
   // To generate a new signing key set the optional expirationSigningKey.
   //
   // Required permission:
   //   - `action.target.write`
-  //
-  // Required feature flag:
-  //   - `actions`
   rpc UpdateTarget (UpdateTargetRequest) returns (UpdateTargetResponse) {
     option (google.api.http) = {
       post: "/v2beta/actions/targets/{id}"
@@ -177,6 +178,7 @@ service ActionService {
     };
 
     option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
+      deprecated: true;
       responses: {
         key: "200";
         value: {
@@ -200,15 +202,14 @@ service ActionService {
 
   // Delete Target
   //
+  // Deprecated: please move to the corresponding endpoint under action service v2. This endpoint will be removed with the next major version of ZITADEL.
+  //
   // Delete an existing target. This will remove it from any configured execution as well.
   // In case the target is not found, the request will return a successful response as
   // the desired state is already achieved.
   //
   // Required permission:
   //   - `action.target.delete`
-  //
-  // Required feature flag:
-  //   - `actions`
   rpc DeleteTarget (DeleteTargetRequest) returns (DeleteTargetResponse) {
     option (google.api.http) = {
       delete: "/v2beta/actions/targets/{id}"
@@ -221,6 +222,7 @@ service ActionService {
     };
 
     option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
+      deprecated: true;
       responses: {
         key: "200";
         value: {
@@ -238,13 +240,12 @@ service ActionService {
 
   // Get Target
   //
+  // Deprecated: please move to the corresponding endpoint under action service v2. This endpoint will be removed with the next major version of ZITADEL.
+  //
   // Returns the target identified by the requested ID.
   //
   // Required permission:
   //   - `action.target.read`
-  //
-  // Required feature flag:
-  //   - `actions`
   rpc GetTarget (GetTargetRequest) returns (GetTargetResponse) {
     option (google.api.http) = {
       get: "/v2beta/actions/targets/{id}"
@@ -257,6 +258,7 @@ service ActionService {
     };
 
     option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
+      deprecated: true;
       responses: {
         key: "200"
         value: {
@@ -280,14 +282,13 @@ service ActionService {
 
   // List targets
   //
+  // Deprecated: please move to the corresponding endpoint under action service v2. This endpoint will be removed with the next major version of ZITADEL.
+  //
   // List all matching targets. By default all targets of the instance are returned.
   // Make sure to include a limit and sorting for pagination.
   //
   // Required permission:
   //   - `action.target.read`
-  //
-  // Required feature flag:
-  //   - `actions`
   rpc ListTargets (ListTargetsRequest) returns (ListTargetsResponse) {
     option (google.api.http) = {
       post: "/v2beta/actions/targets/search",
@@ -301,6 +302,7 @@ service ActionService {
     };
 
     option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
+      deprecated: true;
       responses: {
         key: "200";
         value: {
@@ -324,14 +326,13 @@ service ActionService {
 
   // Set Execution
   //
+  // Deprecated: please move to the corresponding endpoint under action service v2. This endpoint will be removed with the next major version of ZITADEL.
+  //
   // Sets an execution to call a target or include the targets of another execution.
   // Setting an empty list of targets will remove all targets from the execution, making it a noop.
   //
   // Required permission:
   //   - `action.execution.write`
-  //
-  // Required feature flag:
-  //   - `actions`
   rpc SetExecution (SetExecutionRequest) returns (SetExecutionResponse) {
     option (google.api.http) = {
       put: "/v2beta/actions/executions"
@@ -345,6 +346,7 @@ service ActionService {
     };
 
     option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
+      deprecated: true;
       responses: {
         key: "200";
         value: {
@@ -362,14 +364,13 @@ service ActionService {
 
   // List Executions
   //
+  // Deprecated: please move to the corresponding endpoint under action service v2. This endpoint will be removed with the next major version of ZITADEL.
+  //
   // List all matching executions. By default all executions of the instance are returned that have at least one execution target.
   // Make sure to include a limit and sorting for pagination.
   //
   // Required permission:
   //   - `action.execution.read`
-  //
-  // Required feature flag:
-  //   - `actions`
   rpc ListExecutions (ListExecutionsRequest) returns (ListExecutionsResponse) {
     option (google.api.http) = {
       post: "/v2beta/actions/executions/search"
@@ -383,6 +384,7 @@ service ActionService {
     };
 
     option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
+      deprecated: true;
       responses: {
         key: "200";
         value: {
@@ -400,6 +402,8 @@ service ActionService {
 
   // List Execution Functions
   //
+  // Deprecated: please move to the corresponding endpoint under action service v2. This endpoint will be removed with the next major version of ZITADEL.
+  //
   // List all available functions which can be used as condition for executions.
   rpc ListExecutionFunctions (ListExecutionFunctionsRequest) returns (ListExecutionFunctionsResponse) {
     option (google.api.http) = {
@@ -413,6 +417,7 @@ service ActionService {
     };
 
     option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
+      deprecated: true;
       responses: {
         key: "200";
         value: {
@@ -424,6 +429,8 @@ service ActionService {
 
   // List Execution Methods
   //
+  // Deprecated: please move to the corresponding endpoint under action service v2. This endpoint will be removed with the next major version of ZITADEL.
+  //
   // List all available methods which can be used as condition for executions.
   rpc ListExecutionMethods (ListExecutionMethodsRequest) returns (ListExecutionMethodsResponse) {
     option (google.api.http) = {
@@ -437,6 +444,7 @@ service ActionService {
     };
 
     option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
+      deprecated: true;
       responses: {
         key: "200";
         value: {
@@ -448,6 +456,8 @@ service ActionService {
 
   // List Execution Services
   //
+  // Deprecated: please move to the corresponding endpoint under action service v2. This endpoint will be removed with the next major version of ZITADEL.
+  //
   // List all available services which can be used as condition for executions.
   rpc ListExecutionServices (ListExecutionServicesRequest) returns (ListExecutionServicesResponse) {
     option (google.api.http) = {
@@ -461,6 +471,7 @@ service ActionService {
     };
 
     option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
+      deprecated: true;
       responses: {
         key: "200";
         value: {

proto/zitadel/oidc/v2/authorization.proto

@@ -8,6 +8,8 @@ import "protoc-gen-openapiv2/options/annotations.proto";
 
 option go_package = "github.com/zitadel/zitadel/pkg/grpc/oidc/v2;oidc";
 
+// AuthRequest represents an OpenID Connect Authorization Request as defined in
+// https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest
 message AuthRequest{
   option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_schema) = {
     external_docs: {
@@ -15,66 +17,42 @@ message AuthRequest{
       description: "Find out more about OIDC Auth Request parameters";
     }
   };
-  
-  string id = 1 [
-    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
-      description: "ID of the authorization request";
-    }
-  ];
 
-  google.protobuf.Timestamp creation_date = 2 [
+  // The unique identifier of the authorization request.
-    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+  string id = 1;
-      description: "Time when the auth request was created";
-    }
-  ];
 
-  string client_id = 3 [
+  // The timestamp when the authorization request was created.
-    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+  google.protobuf.Timestamp creation_date = 2;
-      description: "OIDC client ID of the application that created the auth request";
-    }
-  ];
 
-  repeated string scope = 4 [
+  // The OAuth2/OIDC client_id of the application that initiated the authorization request.
-    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+  string client_id = 3;
-      description: "Requested scopes by the application, which the user must consent to.";
-    }
-  ];
-  
-  string redirect_uri = 5 [
-    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
-      description: "Base URI that points back to the application";
-    }
-  ];
 
-  repeated Prompt prompt = 6 [
+  // The scopes by the application that the user must consent to.
-    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+  repeated string scope = 4;
-      description: "Prompts that must be displayed to the user";
-    }
-  ];
 
-  repeated string ui_locales = 7 [
+  // The redirect_uri used in the authorization request. This must exactly match one of the redirect URIs registered for the client.
-    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+  // This uri is used to send the authorization code or tokens back to the application.
-      description: "End-User's preferred languages and scripts for the user interface, represented as a list of BCP47 [RFC5646] language tag values, ordered by preference. For instance, the value [fr-CA, fr, en] represents a preference for French as spoken in Canada, then French (without a region designation), followed by English (without a region designation). An error SHOULD NOT result if some or all of the requested locales are not supported.";
+  string redirect_uri = 5;
-    }
-  ];
 
-  optional string login_hint = 8 [
+  // Prompts that must be displayed to the user.
-    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+  repeated Prompt prompt = 6;
-      description: "Login hint can be set by the application with a user identifier such as an email or phone number.";
-    }
-  ];
 
-  optional google.protobuf.Duration max_age = 9 [
+  // End-User's preferred languages and scripts for the user interface, represented as a list of BCP47 [RFC5646]
-    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+  // language tag values, ordered by preference.
-      description: "Specifies the allowable elapsed time in seconds since the last time the End-User was actively authenticated. If the elapsed time is greater than this value, or the field is present with 0 duration, the user must be re-authenticated.";
+  // For instance, the value [fr-CA, fr, en] represents a preference for French as spoken in Canada,
-    }
+  // then French (without a region designation), followed by English (without a region designation).
-  ];
+  // An error SHOULD NOT result if some or all of the requested locales are not supported.
-  
+  repeated string ui_locales = 7;
-  optional string hint_user_id = 10 [
+
-    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+  // Login hint can be set by the application with a user identifier such as an email or phone number.
-      description: "User ID taken from a ID Token Hint if it was present and valid.";
+  optional string login_hint = 8;
-    }
+
-  ];
+  // Specifies the allowable elapsed time in seconds since the last time the End-User was actively authenticated.
+  // If the elapsed time is greater than this value, or the field is present with 0 duration, the user must be re-authenticated.
+  optional google.protobuf.Duration max_age = 9;
+
+  // User ID taken from a ID Token Hint if it was present and valid.
+  optional string hint_user_id = 10;
 }
 
 enum Prompt {
@@ -119,12 +97,16 @@ enum ErrorReason {
 message DeviceAuthorizationRequest {
   // The unique identifier of the device authorization request to be used for authorizing or denying the request.
   string id = 1;
+
   // The client_id of the application that initiated the device authorization request.
   string client_id = 2;
+
   // The scopes requested by the application.
   repeated string scope = 3;
+
   // Name of the client application.
   string app_name = 4;
+
   // Name of the project the client application is part of.
   string project_name = 5;
 }

proto/zitadel/oidc/v2/oidc_service.proto

@@ -101,6 +101,13 @@ option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_swagger) = {
 };
 
 service OIDCService {
+  // Get Auth Request
+  //
+  // Get OIDC Auth Request details by ID, obtained from the redirect URL.
+  // Returns details that are parsed from the application's Auth Request.
+  //
+  // Required permissions:
+  //   - `session.read`
   rpc GetAuthRequest (GetAuthRequestRequest) returns (GetAuthRequestResponse) {
     option (google.api.http) = {
       get: "/v2/oidc/auth_requests/{auth_request_id}"
@@ -113,8 +120,6 @@ service OIDCService {
     };
 
     option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
-      summary: "Get OIDC Auth Request details";
-      description: "Get OIDC Auth Request details by ID, obtained from the redirect URL. Returns details that are parsed from the application's Auth Request."
       responses: {
         key: "200"
         value: {
@@ -124,6 +129,15 @@ service OIDCService {
     };
   }
 
+  // Create Callback
+  //
+  // Finalize an Auth Request and get the callback URL for success or failure.
+  // The user must be redirected to the URL in order to inform the application about the success or failure.
+  // On success, the URL contains details for the application to obtain the tokens.
+  // This method can only be called once for an Auth request.
+  //
+  // Required permissions:
+  //   - `session.link`
   rpc CreateCallback (CreateCallbackRequest) returns (CreateCallbackResponse) {
     option (google.api.http) = {
       post: "/v2/oidc/auth_requests/{auth_request_id}"
@@ -137,8 +151,6 @@ service OIDCService {
     };
 
     option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
-      summary: "Finalize an Auth Request and get the callback URL.";
-      description: "Finalize an Auth Request and get the callback URL for success or failure. The user must be redirected to the URL in order to inform the application about the success or failure. On success, the URL contains details for the application to obtain the tokens. This method can only be called once for an Auth request."
       responses: {
         key: "200"
         value: {
@@ -148,11 +160,14 @@ service OIDCService {
     };
   }
 
-  // Get device authorization request
+  // Get Device Authorization Request
   //
   // Get the device authorization based on the provided "user code".
   // This will return the device authorization request, which contains the device authorization id
   // that is required to authorize the request once the user signed in or to deny it.
+  //
+  // Required permissions:
+  //   - `session.read`
   rpc GetDeviceAuthorizationRequest(GetDeviceAuthorizationRequestRequest) returns (GetDeviceAuthorizationRequestResponse) {
     option (google.api.http) = {
       get: "/v2/oidc/device_authorization/{user_code}"
@@ -174,9 +189,12 @@ service OIDCService {
     };
   }
 
-  // Authorize or deny device authorization
+  // Authorize or Deny Device Authorization
   //
   // Authorize or deny the device authorization request based on the provided device authorization id.
+  //
+  // Required permissions:
+  //   - `session.link`
   rpc AuthorizeOrDenyDeviceAuthorization(AuthorizeOrDenyDeviceAuthorizationRequest) returns (AuthorizeOrDenyDeviceAuthorizationResponse) {
     option (google.api.http) = {
       post: "/v2/oidc/device_authorization/{device_authorization_id}"
@@ -202,12 +220,13 @@ service OIDCService {
 }
 
 message GetAuthRequestRequest {
+  // The ID of the Auth Request, as obtained from the redirect URL.
   string auth_request_id = 1 [
     (validate.rules).string = {min_len: 1, max_len: 200},
+    (google.api.field_behavior) = REQUIRED,
     (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
       min_length: 1;
       max_length: 200;
-      description: "ID of the Auth Request, as obtained from the redirect URL.";
       example: "\"163840776835432705\"";
     }
   ];
@@ -218,52 +237,59 @@ message GetAuthRequestResponse {
 }
 
 message CreateCallbackRequest {
+  // The ID of the Auth Request to finalize.
   string auth_request_id = 1 [
     (validate.rules).string = {min_len: 1, max_len: 200},
     (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
-      description: "ID of the Auth Request.";
       example: "\"163840776835432705\"";
-    }
+    },
+    (google.api.field_behavior) = REQUIRED
   ];
 
+  // The result of the authorization flow, either success with the user's session or failure with an error.
   oneof callback_kind {
     option (validate.required) = true;
+
+    // The session of the authenticated user, to finalize the authorization request.
     Session session = 2;
-    AuthorizationError error = 3 [
+
-      (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+    // The error that occurred during the authorization flow, to inform the application.
-        description: "Set this field when the authorization flow failed. It creates a callback URL to the application, with the error details set.";
+    // This creates a callback URL with the error details set.
-        ref: "https://openid.net/specs/openid-connect-core-1_0.html#AuthError";
+    // See: https://openid.net/specs/openid-connect-core-1_0.html#AuthError
-      }
+    AuthorizationError error = 3;
-    ];
   }
 }
 
 message Session {
+  // ID of the session, used to login the user. Connects the session to the Auth Request.
   string session_id = 1 [
     (validate.rules).string = {min_len: 1, max_len: 200},
     (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
       min_length: 1;
       max_length: 200;
-      description: "ID of the session, used to login the user. Connects the session to the Auth Request.";
       example: "\"163840776835432705\"";
-    }
+    },
+    (google.api.field_behavior) = REQUIRED
   ];
 
+  // Token of the session used to login the user. This token verifies that the session is valid.
   string session_token = 2 [
     (validate.rules).string = {min_len: 1, max_len: 200},
     (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
       min_length: 1;
       max_length: 200;
-      description: "Token to verify the session is valid";
+    },
-    }
+    (google.api.field_behavior) = REQUIRED
   ];
 }
 
 message CreateCallbackResponse {
   zitadel.object.v2.Details details = 1;
+  // The callback URL where the user should be redirected using an HTTP "302 FOUND" status.
+  // This contains details for the application to obtain the tokens on success, or error details on failure.
+  // Note that this field must be treated as credentials, as the contained code can be used to obtain tokens on behalf of the user."
   string callback_url = 2 [
     (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
-      description: "Callback URL where the user should be redirected, using a \"302 FOUND\" status. Contains details for the application to obtain the tokens on success, or error details on failure. Note that this field must be treated as credentials, as the contained code can be used to obtain tokens on behalve of the user.";
       example: "\"https://client.example.org/cb?code=SplxlOBeZQQYbYS6WxSbIA&state=af0ifjsldkj\""
     }
   ];
@@ -277,7 +303,8 @@ message GetDeviceAuthorizationRequestRequest {
       min_length: 9;
       max_length: 9;
       example: "\"K9LV-3DMQ\"";
-    }
+    },
+    (google.api.field_behavior) = REQUIRED
   ];
 }
 
@@ -292,7 +319,8 @@ message AuthorizeOrDenyDeviceAuthorizationRequest {
     (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
       min_length: 1;
       max_length: 200;
-    }
+    },
+    (google.api.field_behavior) = REQUIRED
   ];
 
   // The decision of the user to authorize or deny the device authorization request.

proto/zitadel/oidc/v2beta/oidc_service.proto

@@ -100,7 +100,13 @@ option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_swagger) = {
   }
 };
 
+// Deprecated: use oidc service v2 instead. This service will be removed in the next major version of ZITADEL.
 service OIDCService {
+  // Get AuthRequest
+  //
+  // Deprecated: please move to the corresponding endpoint under oidc service v2. This endpoint will be removed with the next major version of ZITADEL.
+  //
+  // Get OIDC Auth Request details by ID, obtained from the redirect URL. Returns details that are parsed from the application's Auth Request.
   rpc GetAuthRequest (GetAuthRequestRequest) returns (GetAuthRequestResponse) {
     option (google.api.http) = {
       get: "/v2beta/oidc/auth_requests/{auth_request_id}"
@@ -113,8 +119,7 @@ service OIDCService {
     };
 
     option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
-      summary: "Get OIDC Auth Request details";
+      deprecated: true;
-      description: "Get OIDC Auth Request details by ID, obtained from the redirect URL. Returns details that are parsed from the application's Auth Request."
       responses: {
         key: "200"
         value: {
@@ -124,6 +129,14 @@ service OIDCService {
     };
   }
 
+  // Create Callback
+  //
+  // Deprecated: please move to the corresponding endpoint under oidc service v2. This endpoint will be removed with the next major version of ZITADEL.
+  //
+  // Finalize an Auth Request and get the callback URL for success or failure.
+  // The user must be redirected to the URL in order to inform the application about the success or failure.
+  // On success, the URL contains details for the application to obtain the tokens.
+  // This method can only be called once for an Auth request.
   rpc CreateCallback (CreateCallbackRequest) returns (CreateCallbackResponse) {
     option (google.api.http) = {
       post: "/v2beta/oidc/auth_requests/{auth_request_id}"
@@ -137,8 +150,7 @@ service OIDCService {
     };
 
     option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
-      summary: "Finalize an Auth Request and get the callback URL.";
+      deprecated: true;
-      description: "Finalize an Auth Request and get the callback URL for success or failure. The user must be redirected to the URL in order to inform the application about the success or failure. On success, the URL contains details for the application to obtain the tokens. This method can only be called once for an Auth request."
       responses: {
         key: "200"
         value: {

proto/zitadel/saml/v2/authorization.proto

@@ -8,6 +8,8 @@ import "protoc-gen-openapiv2/options/annotations.proto";
 
 option go_package = "github.com/zitadel/zitadel/pkg/grpc/saml/v2;saml";
 
+// SAMLRequest contains information about a SAML authentication request.
+// see: https://docs.oasis-open.org/security/saml/Post2.0/sstc-saml-tech-overview-2.0.html
 message SAMLRequest{
   option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_schema) = {
     external_docs: {
@@ -15,42 +17,24 @@ message SAMLRequest{
       description: "Find out more about SAMLRequest parameters";
     }
   };
-  
-  string id = 1 [
-    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
-      description: "ID of the SAMLRequest";
-    }
-  ];
 
-  google.protobuf.Timestamp creation_date = 2 [
+  // ID of the created SAMLRequest.
-    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+  string id = 1;
-      description: "Time when the SAMLRequest was created";
-    }
-  ];
 
-  string issuer = 3 [
+  // Time when the SAMLRequest was created.
-    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+  google.protobuf.Timestamp creation_date = 2;
-      description: "SAML entityID of the application that created the SAMLRequest";
-    }
-  ];
-  
-  string assertion_consumer_service = 4 [
-    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
-      description: "URL which points back to the assertion consumer service of the application";
-    }
-  ];
 
-  string relay_state = 5 [
+  // SAML entityID of the application that created the SAMLRequest.
-    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+  string issuer = 3;
-      description: "RelayState provided by the application for the request";
-    }
-  ];
 
-  string binding = 6 [
+  // URL which points back to the assertion consumer service of the application that created the SAMLRequest.
-    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+  string assertion_consumer_service = 4;
-      description: "Binding used by the application for the request";
+
-    }
+  // RelayState provided by the application for the request.
-  ];
+  string relay_state = 5;
+
+  // Binding used by the application for the request.
+  string binding = 6;
 }
 
 message AuthorizationError {

proto/zitadel/saml/v2/saml_service.proto

@@ -101,6 +101,12 @@ option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_swagger) = {
 };
 
 service SAMLService {
+  // Get SAML Request
+  //
+  // Get SAML Request details by ID. Returns details that are parsed from the application's SAML Request.
+  //
+  // Required permissions:
+  //   - `session.read`
   rpc GetSAMLRequest (GetSAMLRequestRequest) returns (GetSAMLRequestResponse) {
     option (google.api.http) = {
       get: "/v2/saml/saml_requests/{saml_request_id}"
@@ -113,8 +119,6 @@ service SAMLService {
     };
 
     option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
-      summary: "Get SAML Request details";
-      description: "Get SAML Request details by ID. Returns details that are parsed from the application's SAML Request."
       responses: {
         key: "200"
         value: {
@@ -124,6 +128,15 @@ service SAMLService {
     };
   }
 
+  // Create Response
+  //
+  // Finalize a SAML Request and get the response definition for success or failure.
+  // The response must be handled as per the SAML definition to inform the application about the success or failure.
+  // On success, the response contains details for the application to obtain the SAMLResponse.
+  // This method can only be called once for an SAML request.
+  //
+  // Required permissions:
+  //   - `session.link`
   rpc CreateResponse (CreateResponseRequest) returns (CreateResponseResponse) {
     option (google.api.http) = {
       post: "/v2/saml/saml_requests/{saml_request_id}"
@@ -137,8 +150,6 @@ service SAMLService {
     };
 
     option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
-      summary: "Finalize a SAML Request and get the response.";
-      description: "Finalize a SAML Request and get the response definition for success or failure. The response must be handled as per the SAML definition to inform the application about the success or failure. On success, the response contains details for the application to obtain the SAMLResponse. This method can only be called once for an SAML request."
       responses: {
         key: "200"
         value: {
@@ -153,6 +164,7 @@ message GetSAMLRequestRequest {
   // ID of the SAML Request, as obtained from the redirect URL.
   string saml_request_id = 1 [
     (validate.rules).string = {min_len: 1, max_len: 200},
+    (google.api.field_behavior) = REQUIRED,
     (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
       min_length: 1;
       max_length: 200;
@@ -169,14 +181,19 @@ message CreateResponseRequest {
   // ID of the SAML Request.
   string saml_request_id = 1 [
     (validate.rules).string = {min_len: 1, max_len: 200},
+    (google.api.field_behavior) = REQUIRED,
     (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
       example: "\"163840776835432705\"";
     }
   ];
 
+  // The result of the authorization flow, either success with the user's session or failure with an error.
   oneof response_kind {
     option (validate.required) = true;
+
+    // The session of the authenticated user, to finalize the authorization request.
     Session session = 2;
+
     // Set this field when the authorization flow failed. It creates a response depending on the SP, with the error details set.
     AuthorizationError error = 3;
   }
@@ -186,6 +203,7 @@ message Session {
   // ID of the session, used to login the user. Connects the session to the SAML Request.
   string session_id = 1 [
     (validate.rules).string = {min_len: 1, max_len: 200},
+    (google.api.field_behavior) = REQUIRED,
     (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
       min_length: 1;
       max_length: 200;
@@ -196,6 +214,7 @@ message Session {
   // Token to verify the session is valid.
   string session_token = 2 [
     (validate.rules).string = {min_len: 1, max_len: 200},
+    (google.api.field_behavior) = REQUIRED,
     (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
       min_length: 1;
       max_length: 200;
@@ -205,23 +224,30 @@ message Session {
 
 message CreateResponseResponse {
   zitadel.object.v2.Details details = 1;
+
   // URL including the Assertion Consumer Service where the user should be redirected or has to call per POST, depending on the binding. Contains details for the application to obtain the response on success, or error details on failure. Note that this field must be treated as credentials, as the contained SAMLResponse or code can be used on behalve of the user.
   string url = 2 [
     (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
       example: "\"https://client.example.org/cb\""
     }
   ];
+
   // Binding is defined through the request, what the IDP is able to use and what bindings are available for the SP.
   oneof binding {
     // Set if the binding is Redirect-Binding, where the user can directly be redirected to the application, using a \"302 FOUND\" status to the URL.
     RedirectResponse redirect = 3;
+
     // Set if the binding is POST-Binding, where the application expects to be called per HTTP POST with the SAMLResponse and RelayState in the form body.
     PostResponse post = 4;
   }
 }
 
 message RedirectResponse{}
+
 message PostResponse{
+  // The SAML RelaySate, that needs to be returned to the application to match the response to the request.
   string relay_state = 1;
+
+  // The SAML Response, that needs to be returned to the application to complete the SAML flow.
   string saml_response = 2;
 }

proto/zitadel/session/v2/challenge.proto

@@ -18,28 +18,37 @@ enum UserVerificationRequirement {
 
 message RequestChallenges {
   message WebAuthN {
+    // The domain on which the session was created. Will be used in the WebAuthN challenge.
+    // It must be either the exact domain or a top-level domain of the origin of the request.
+    // For example if the request is coming from "login.example.com", the domain can be
+    // "login.example.com" or "example.com", but not "other.com" or "sub.login.example.com".
+    // See also: https://www.w3.org/TR/webauthn/#relying-party-identifier
     string domain = 1 [
       (validate.rules).string = {min_len: 1, max_len: 200},
-      (google.api.field_behavior) = REQUIRED,
+      (google.api.field_behavior) = REQUIRED
-      (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
-        description: "\"Domain on which the session was created. Will be used in the WebAuthN challenge.\"";
-      }
     ];
+
+    // User verification that is required during validation.
+    // When set to `USER_VERIFICATION_REQUIREMENT_REQUIRED` the behaviour is for passkey authentication.
+    // Other values will mean U2F.
+    // See also: https://www.w3.org/TR/webauthn/#enum-userVerificationRequirement
+    // If either the value is set to USER_VERIFICATION_REQUIREMENT_REQUIRED or the user verification
+    // is passed as part of the authentication ceremony, the user_verified flag will be set in the resulting webauthn factor.
     UserVerificationRequirement user_verification_requirement = 2 [
       (validate.rules).enum = {
         defined_only: true,
         not_in: [0]
       },
-      (google.api.field_behavior) = REQUIRED,
+      (google.api.field_behavior) = REQUIRED
-      (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
-        description: "\"User verification that is required during validation. When set to `USER_VERIFICATION_REQUIREMENT_REQUIRED` the behaviour is for passkey authentication. Other values will mean U2F\"";
-        ref: "https://www.w3.org/TR/webauthn/#enum-userVerificationRequirement";
-      }
     ];
   }
+
   message OTPSMS {
+    // Request the code to be returned instead of sending an SMS.
+    // This is useful for testing or in case you want to send the code yourself.
     bool return_code = 1;
   }
+
   message OTPEmail {
     message SendCode {
       // Optionally set a url_template, which will be used in the mail sent by ZITADEL to guide the user to your verification page.
@@ -64,16 +73,27 @@ message RequestChallenges {
     }
   }
 
+  // WebAuthN requests a challenge to be used in the WebAuthN authentication ceremony.
+  // They can be used for both passkey and U2F authentication.
+  // They're required for a webauthn check at the SetSession endpoint.
   optional WebAuthN web_auth_n = 1;
+
+  // OTPSMS requests a code to be sent via SMS to the user's primary phone.
+  // It is required for an OTP check at the SetSession endpoint.
   optional OTPSMS otp_sms = 2;
+
+  // OTPEmail requests a code to be sent via email to the user's primary email address.
+  // It is required for an OTP check at the SetSession endpoint.
   optional OTPEmail otp_email = 3;
 }
 
 message Challenges {
+  // WebAuthN contains the options for the Assertion Generation (dictionary PublicKeyCredentialRequestOptions).
+  // Generated helper methods transform the field to JSON, for use in a WebauthN client.
+  // See also: https://www.w3.org/TR/webauthn/#dictdef-publickeycredentialrequestoptions
   message WebAuthN {
     google.protobuf.Struct public_key_credential_request_options = 1 [
       (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
-        description: "Options for Assertion Generaration (dictionary PublicKeyCredentialRequestOptions). Generated helper methods transform the field to JSON, for use in a WebauthN client. See also: https://www.w3.org/TR/webauthn/#dictdef-publickeycredentialrequestoptions"
         example: "{\"publicKey\":{\"allowCredentials\":[{\"id\":\"ATmqBg-99qyOZk2zloPdJQyS2R7IkFT7v9Hoos_B_nM\",\"type\":\"public-key\"}],\"challenge\":\"GAOHYz2jE69kJMYo6Laij8yWw9-dKKgbViNhfuy0StA\",\"rpId\":\"localhost\",\"timeout\":300000,\"userVerification\":\"required\"}}"
       }
     ];

proto/zitadel/session/v2/session.proto

@@ -10,42 +10,38 @@ import "validate/validate.proto";
 option go_package = "github.com/zitadel/zitadel/pkg/grpc/session/v2;session";
 
 message Session {
-  string id = 1 [
+  // Unique identifier of the session.
-    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+  string id = 1;
-      description: "\"id of the session\"";
+
-    }
+  // The timestamp the session was created.
-  ];
+  google.protobuf.Timestamp creation_date = 2;
-  google.protobuf.Timestamp creation_date = 2 [
+
-    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+  // The timestamp the session was last updated.
-      description: "\"time when the session was created\"";
+  google.protobuf.Timestamp change_date = 3;
-    }
+
-  ];
+  // The sequence of the session represents the change sequence of the session.
-  google.protobuf.Timestamp change_date = 3 [
+  uint64 sequence = 4;
-    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+
-      description: "\"time when the session was last updated\"";
+  // The factors that have been checked for this session, e.g. the user, password and more.
-    }
+  // If a factor is set, it means it has been checked and is valid.
-  ];
+  // If a factor is not set, it means it has not been checked or is invalid.
-  uint64 sequence = 4 [
+  // If a factor is set, the verified_at timestamp indicates when it was last checked.
-    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+  Factors factors = 5;
-      description: "\"sequence of the session\"";
+
-    }
+  // Metadata contains custom key value pairs set by the user.
-  ];
+  // The metadata is not interpreted by ZITADEL and can be used to store any information
-  Factors factors = 5 [
+  // relevant to the session.
-    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+  map<string, bytes> metadata = 6;
-      description: "\"checked factors of the session, e.g. the user, password and more\"";
+
-    }
+  // UserAgent contains information about the user agent used to create the session.
-  ];
+  // This can include information such as the IP address, browser type, and operating system and
-  map<string, bytes> metadata = 6 [
+  // a fingerprint id.
-    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+  // This can be used to identify and filter sessions based on the user agent.
-      description: "\"custom key value list\"";
-    }
-  ];
   UserAgent user_agent = 7;
-  optional google.protobuf.Timestamp expiration_date = 8 [
+
-    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+  // ExpirationDate is the time the session will be automatically invalidated.
-      description: "\"time the session will be automatically invalidated\"";
+  // If not set, the session does not expire automatically.
-    }
+  optional google.protobuf.Timestamp expiration_date = 8;
-  ];
 }
 
 message Factors {
@@ -61,102 +57,100 @@ message Factors {
 message UserFactor {
   reserved 5;
   reserved "organisation_id";
-  google.protobuf.Timestamp verified_at = 1 [
+
-    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+  // The timestamp when the user was last verified.
-      description: "\"time when the user was last checked\"";
+  google.protobuf.Timestamp verified_at = 1;
-    }
+
-  ];
+  // The unique identifier of the user that was verified.
-  string id = 2 [
+  string id = 2;
-    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+
-      description: "\"id of the checked user\"";
+  // The login name of the user that was verified.
-    }
+  string login_name = 3;
-  ];
+
-  string login_name = 3 [
+  // The display name of the user that was verified.
-    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+  string display_name = 4;
-      description: "\"login name of the checked user\"";
+
-    }
+  // The id of the organization the user belongs to.
-  ];
+  string organization_id = 6;
-  string display_name = 4 [
-    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
-      description: "\"display name of the checked user\"";
-    }
-  ];
-  string organization_id = 6 [
-    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
-      description: "\"organization id of the checked user\"";
-    }
-  ];
 }
 
 message PasswordFactor {
-  google.protobuf.Timestamp verified_at = 1 [
+  // The timestamp when the password was last verified.
-    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+  google.protobuf.Timestamp verified_at = 1;
-      description: "\"time when the password was last checked\"";
-    }
-  ];
 }
 
 message IntentFactor {
-  google.protobuf.Timestamp verified_at = 1 [
+  // The timestamp when the intent was last verified.
-    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+  google.protobuf.Timestamp verified_at = 1;
-      description: "\"time when an intent was last checked\"";
-    }
-  ];
 }
 
 message WebAuthNFactor {
-  google.protobuf.Timestamp verified_at = 1 [
+  // The timestamp when the passkey challenge was last verified.
-    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+  google.protobuf.Timestamp verified_at = 1;
-      description: "\"time when the passkey challenge was last checked\"";
+
-    }
+  // Indicates if the user presence was verified during the last challenge.
-  ];
+  // This can be used to determine if the factor can be considered as multi-factor authentication.
   bool user_verified = 2;
 }
 
 message TOTPFactor {
-  google.protobuf.Timestamp verified_at = 1 [
+  // The timestamp when the Time-based One-Time Password was last verified.
-    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+  google.protobuf.Timestamp verified_at = 1;
-      description: "\"time when the Time-based One-Time Password was last checked\"";
-    }
-  ];
 }
 
 message OTPFactor {
-  google.protobuf.Timestamp verified_at = 1 [
+  // The timestamp when the One-Time Password was last verified either by SMS or Email.
-    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+  google.protobuf.Timestamp verified_at = 1;
-      description: "\"time when the One-Time Password was last checked\"";
-    }
-  ];
 }
 
 message SearchQuery {
   oneof query {
     option (validate.required) = true;
 
+    // Search for sessions with the given IDs.
     IDsQuery ids_query = 1;
+
+    // Search for sessions of the given user ID.
     UserIDQuery user_id_query = 2;
+
+    // Search for sessions based on their creation date.
+    // This can be used to find sessions created before or after a certain date.
     CreationDateQuery creation_date_query = 3;
+
+    // Search for sessions created by a specific user.
     CreatorQuery creator_query = 4;
+
+    // Search for sessions based on the user agent used to create the session.
+    // It can be used to find sessions created from a specific device or browser.
+    // This is typically done for providing a list of active sessions to the user
+    // in a user interface.
     UserAgentQuery user_agent_query = 5;
+
+    // Search for sessions based on their expiration date.
+    // This can be used to find sessions that are set to expire before or after a certain date.
     ExpirationDateQuery expiration_date_query = 6;
   }
 }
 
 message IDsQuery {
+  // List of session IDs to search for.
+  // If multiple IDs are provided, sessions matching any of the IDs will be returned.
   repeated string ids = 1;
 }
 
 message UserIDQuery {
+  // ID of the user whose sessions are being searched for.
   string id = 1;
 }
 
 message CreationDateQuery {
+  // The creation date to compare the session's creation date against.
   google.protobuf.Timestamp creation_date = 1;
+
+  // The method of comparison to use for the creation date.
+  // This defines whether to search for sessions created before, after, or exactly at the specified date.
   zitadel.v1.TimestampQueryMethod method = 2 [
-    (validate.rules).enum.defined_only = true,
+    (validate.rules).enum.defined_only = true
-    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
-      description: "defines which timestamp comparison method is used";
-    }
   ];
 }
 
@@ -185,18 +179,25 @@ message UserAgentQuery {
 }
 
 message ExpirationDateQuery {
+  // The expiration date to compare the session's expiration date against.
   google.protobuf.Timestamp expiration_date = 1;
+
+  // The method of comparison to use for the expiration date.
+  // This defines whether to search for sessions expiring before, after, or exactly at the specified date.
   zitadel.v1.TimestampQueryMethod method = 2 [
-    (validate.rules).enum.defined_only = true,
+    (validate.rules).enum.defined_only = true
-    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
-      description: "defines which timestamp comparison method is used";
-    }
   ];
 }
 
 message UserAgent {
+  // FingerprintID is a unique identifier for the user agent's fingerprint.
+  // It can be used to group sessions by device or browser.
   optional string fingerprint_id = 1;
+
+  // IP is the IP address from which the session was created.
   optional string ip = 2;
+
+  // Description is a human-readable description of the user agent.
   optional string description = 3;
 
   // A header may have multiple values.

proto/zitadel/session/v2/session_service.proto

@@ -106,7 +106,14 @@ option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_swagger) = {
 
 service SessionService {
 
-  // Search sessions
+  // List sessions
+  //
+  // Searches for sessions matching the given query. You can search by session ID, user ID,
+  // creation date, creator, user agent or expiration date.
+  //
+  // Required permissions:
+  //   - `session.read`
+  //   - no permission required to search for own sessions
   rpc ListSessions (ListSessionsRequest) returns (ListSessionsResponse) {
     option (google.api.http) = {
       post: "/v2/sessions/search"
@@ -120,8 +127,6 @@ service SessionService {
     };
 
     option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
-      summary: "Search sessions";
-      description: "Search for sessions"
       responses: {
         key: "200"
         value: {
@@ -142,7 +147,19 @@ service SessionService {
     };
   }
 
-  // GetSession a session
+  // Get Session
+  //
+  // Retrieve a session by its ID. Returns all information about the session, including
+  // the factors that were verified, the metadata, user agent information and possible expiration date.
+  // The session token is required unless either of the following conditions is met:
+  //   - the caller created the session
+  //   - the authenticated user requests their own session (checked user)
+  //   - the security token provided in the authorization header has the same user agent as the session
+  //   - the caller is granted the permission session.read permission on either the instance or on the checked user's organization
+  //
+  // Required permissions:
+  //   - `session.read`
+  //   - no permission required to get own sessions (see above) or when providing the current session token
   rpc GetSession (GetSessionRequest) returns (GetSessionResponse) {
     option (google.api.http) = {
       get: "/v2/sessions/{session_id}"
@@ -155,8 +172,6 @@ service SessionService {
     };
 
     option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
-      summary: "Get a session";
-      description: "Get a session and all its information like the time of the user or password verification"
       responses: {
         key: "200"
         value: {
@@ -166,7 +181,16 @@ service SessionService {
     };
   }
 
-  // Create a new session
+  // Create Session
+  //
+  // Create a new session with initial checks, metadata and challenges for further verification.
+  // A token will be returned, which is required for using the session as authentication, e.g.
+  // when authenticating an OIDC auth request or SAML request.
+  // Additionally, the session token can be used as OAuth2 access token to authenticate against
+  // the ZITADEL APIs.
+  //
+  // Required permissions:
+  //   - `session.write`
   rpc CreateSession (CreateSessionRequest) returns (CreateSessionResponse) {
     option (google.api.http) = {
       post: "/v2/sessions"
@@ -183,8 +207,6 @@ service SessionService {
     };
 
     option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
-      summary: "Create a new session";
-      description: "Create a new session. A token will be returned, which is required for further updates of the session."
       responses: {
         key: "200"
         value: {
@@ -194,7 +216,14 @@ service SessionService {
     };
   }
 
-  // Update a session
+  // Set Session
+  //
+  // Update an existing session with new information like additional checks or metadata
+  // or request additional challenges.
+  // A new session token will be returned. Note that the previous token will be invalidated.
+  //
+  // Required permissions:
+  //   - `session.write`
   rpc SetSession (SetSessionRequest) returns (SetSessionResponse) {
     option (google.api.http) = {
       patch: "/v2/sessions/{session_id}"
@@ -208,8 +237,6 @@ service SessionService {
     };
 
     option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
-      summary: "Update an existing session";
-      description: "Update an existing session with new information."
       responses: {
         key: "200"
         value: {
@@ -219,7 +246,17 @@ service SessionService {
     };
   }
 
-  // Terminate a session
+  // DeleteSession
+  //
+  // Terminate an existing session. This invalidates the session and its token.
+  // The session can no longer be used for the authentication of other resources
+  // or to authenticate against the ZITADEL APIs.
+  //
+  // You can only terminate your own session, unless you are granted the `session.delete` permission.
+  //
+  // Required permissions:
+  //   - `session.delete`
+  //   - no permission required for own sessions or when providing the current session token
   rpc DeleteSession (DeleteSessionRequest) returns (DeleteSessionResponse) {
     option (google.api.http) = {
       delete: "/v2/sessions/{session_id}"
@@ -233,8 +270,6 @@ service SessionService {
     };
 
     option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
-      summary: "Terminate an existing session";
-      description: "Terminate your own session or if granted any other session."
       responses: {
         key: "200"
         value: {
@@ -246,41 +281,89 @@ service SessionService {
 }
 
 message ListSessionsRequest{
+  // List limitations and ordering.
   zitadel.object.v2.ListQuery query = 1;
+
+  // The criteria to be used when searching for sessions.
+  // Multiple queries will be combined with a logical AND.
   repeated SearchQuery queries = 2;
+
+  // The column to be used for sorting the sessions.
   zitadel.session.v2.SessionFieldName sorting_column = 3;
 }
 
 message ListSessionsResponse{
+  // Contains details about the response, such as the total number of sessions.
   zitadel.object.v2.ListDetails details = 1;
+
+  // The sessions matching the search query. There might be more sessions available
+  // than returned in this response. Use the details field to see if there are more sessions
+  // available and to get the total count of sessions matching the query.
   repeated Session sessions = 2;
 }
 
 message GetSessionRequest{
-  string session_id = 1;
+  // The unique identifier of the session to be retrieved.
-  optional string session_token = 2;
+  string session_id = 1 [
+    (validate.rules).string = {min_len: 1, max_len: 200},
+    (google.api.field_behavior) = REQUIRED,
+    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+      min_length: 1;
+      max_length: 200;
+      example: "\"222430354126975533\"";
+    }
+  ];
+
+  // The current token of the session, previously returned on the create / update request.
+  // The token is required unless either of the following conditions is met:
+  // - the caller created the session
+  // - the authenticated user requests their own session (checked user)
+  // - the security token provided in the authorization header has the same user agent as the session
+  // - the caller is granted the permission session.read permission on either the instance or on the checked user's organization
+  optional string session_token = 2 [
+    (validate.rules).string = {min_len: 1, max_len: 200},
+    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+      min_length: 1;
+      max_length: 200;
+      example: "\"222430354126975533\"";
+    }
+   ];
 }
+
 message GetSessionResponse{
   Session session = 1;
 }
 
 message CreateSessionRequest{
-  Checks checks = 1 [
+  // The checks to be performed during session creation.
-    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+  // Note that a user check can only be performed once per session and cannot be changed afterwards.
-      description: "\"Check for user and password. Successful checks will be stated as factors on the session.\"";
+  // Some checks require that the user is already checked, either in the previous or the same
-    }
+  // request. For example, a password check requires that the user is already checked.
-  ];
+  // Other checks, like WebAuthN or IDP intent, require that the user is already checked and a challenge
-  map<string, bytes> metadata = 2 [
+  // was requested in any previous request.
-    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+  // On successful checks, the session's `factors` field will be updated.
-      description: "\"custom key value list to be stored on the session\"";
+  Checks checks = 1;
-    }
+
-  ];
+  // Custom key value list to be stored on the session.
+  map<string, bytes> metadata = 2;
+
+  // Challenges to be requested for further verification.
+  // The challenges will be created and returned in the response.
+  // The challenges can then be used for further checks with the following SetSession method.
   RequestChallenges challenges = 3;
+
+  // Store information about the user agent of the client.
+  // This information is stored on the session and can be used for auditing or security purposes.
+  // Sessions can also be filtered by user agent information.
   UserAgent user_agent = 4;
+
+  // Duration after which the session will be automatically invalidated.
+  // If not set, the session will not expire automatically and must be deleted manually.
+  // Note that an expired session cannot be used for authentication anymore, but will still be listed
+  // until it is deleted.
   optional google.protobuf.Duration lifetime = 5 [
     (validate.rules).duration = {gt: {seconds: 0}},
     (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
-      description: "\"duration (in seconds) after which the session will be automatically invalidated\"";
       example:"\"18000s\""
     }
   ];
@@ -288,53 +371,74 @@ message CreateSessionRequest{
 
 message CreateSessionResponse{
   zitadel.object.v2.Details details = 1;
+
+  // Unique identifier of the session.
   string session_id = 2 [
     (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
-      description: "\"id of the session\"";
       example: "\"222430354126975533\"";
     }
   ];
-  string session_token = 3 [
+
-    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+  // The current token of the session, which is required for using the session as authentication,
-      description: "\"The current token of the session, which is required for delete session, get session or the request of other resources.\"";
+  // e.g.when authenticating an OIDC auth request or SAML request.
-    }
+  // Additionally, the session token can be used as OAuth2 access token to authenticate against
-  ];
+  // the ZITADEL APIs.
+  string session_token = 3;
+
+  // The challenges that were requested for the session.
+  // The challenges can be used for further checks with the SetSession method.
   Challenges challenges = 4;
 }
 
 message SetSessionRequest{
+  // The unique identifier of the session to be updated.
   string session_id = 1 [
     (validate.rules).string = {min_len: 1, max_len: 200},
+    (google.api.field_behavior) = REQUIRED,
     (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
       min_length: 1;
       max_length: 200;
-      description: "\"id of the session to update\"";
       example: "\"222430354126975533\"";
     }
   ];
+
+  // Deprecated: the session token is no longer required when updating a session
+  // and will be ignored when provided.
   string session_token = 2 [
-    (validate.rules).string = {min_len: 0, max_len: 200},
+    deprecated=true
-    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
-      min_length: 1;
-      max_length: 200;
-      description: "\"DEPRECATED: this field is ignored.\"";
-    }
-  ];
-  Checks checks = 3[
-    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
-      description: "\"Check for user and password. Successful checks will be stated as factors on the session.\"";
-    }
-  ];
-  map<string, bytes> metadata = 4 [
-    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
-      description: "\"custom key value list to be stored on the session\"";
-    }
   ];
+
+  // Additional checks to be performed on the session.
+  // Successful checks will be stated as factors on the session.
+  // Re-executing a check that was already successful will overwrite the previous check time.
+  // For example, if a password check was already successful, it can be re-checked to update the check time.
+  // Note that a user check can only be performed once per session and cannot be changed afterwards.
+  // Some checks require that the user is already checked, either in the previous or the same request.
+  // For example, a password check requires that the user is already checked.
+  // Other checks, like WebAuthN or IDP intent, require that the user is already checked and a challenge
+  // was requested in any previous request.
+  // On successful checks, the session's `factors` field will be updated.
+  Checks checks = 3;
+
+  // Additional custom key value pairs to be stored on the session.
+  // Existing keys will be overwritten. To delete a key, set its value to an empty byte array.
+  // Note that metadata keys cannot be changed once the session has been created.
+  // You need to create a new entry and delete the old one instead.
+  map<string, bytes> metadata = 4;
+
+  // Additional challenges to be requested for further verification.
+  // The challenges will be created and returned in the response.
+  // The challenges can then be used for further checks with the following SetSession method.
+  // Requesting a challenge that was already requested will overwrite the previous challenge.
   RequestChallenges challenges = 5;
+
+  // Update the duration after which the session will be automatically invalidated.
+  // If not set, the lifetime will not be changed.
+  // Note that an expired session cannot be used for authentication anymore, but will still be listed
+  // until it is deleted.
   optional google.protobuf.Duration lifetime = 6 [
     (validate.rules).duration = {gt: {seconds: 0}},
     (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
-      description: "\"duration (in seconds) after which the session will be automatically invalidated\"";
       example:"\"18000s\""
     }
   ];
@@ -342,29 +446,38 @@ message SetSessionRequest{
 
 message SetSessionResponse{
   zitadel.object.v2.Details details = 1;
-  string session_token = 2 [
+
-    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+  // The current token of the session, which is required for using the session as authentication,
-      description: "\"The current token of the session, which is required for delete session, get session or the request of other resources.\"";
+  // e.g.when authenticating an OIDC auth request or SAML request.
-    }
+  // Additionally, the session token can be used as OAuth2 access token to authenticate against
-  ];
+  // the ZITADEL APIs.
+  // The previous token was invalidated and can no longer be used.
+  string session_token = 2;
+
+  // The challenges that were requested for the session.
+  // The challenges can be used for further checks with the SetSession method.
   Challenges challenges = 3;
 }
 
 message DeleteSessionRequest{
+  // The unique identifier of the session to be terminated.
   string session_id = 1 [
     (validate.rules).string = {min_len: 1, max_len: 200},
+    (google.api.field_behavior) = REQUIRED,
     (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
       min_length: 1;
       max_length: 200;
-      description: "\"id of the session to terminate\"";
       example: "\"222430354126975533\"";
     }
   ];
-  optional string session_token = 2 [
+
-    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+  // The current token of the session, previously returned on the create / update request.
-      description: "\"The current token of the session, previously returned on the create / update request. The token is required unless the authenticated user terminates the own session or is granted the `session.delete` permission.\"";
+  // The token is required unless either of the following conditions is met:
-    }
+  // - the caller created the session
-  ];
+  // - the authenticated user requests their own session (checked user)
+  // - the security token provided in the authorization header has the same user agent as the session
+  // - the caller is granted the permission session.delete permission on either the instance or on the checked user's organization
+  optional string session_token = 2;
 }
 
 message DeleteSessionResponse{
@@ -372,55 +485,82 @@ message DeleteSessionResponse{
 }
 
 message Checks {
-  optional CheckUser user = 1 [
+  // Check the user by its user ID or login name.
-    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+  // A user check can only be performed once per session and cannot be changed afterwards.
-      description: "\"checks the user and updates the session on success\"";
+  // On successful user check, the session's `factors` field will be updated with a `user` factor
-    }
+  // containing the checked user's ID, login name, display name, organization ID and verification time.
-  ];
+  // Note that some other checks require that the user is already checked, either in the previous
-  optional CheckPassword password = 2 [
+  // or the same request. For example, a password check requires that the user is already checked.
-    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+  optional CheckUser user = 1;
-      description: "\"Checks the password and updates the session on success. Requires that the user is already checked, either in the previous or the same request. On failed password check id: \"COMMAND-3M0fs\" wll be returned. On user locked out id: \"COMMAND-JLK35\"/\"COMMAND-SFA3t\" will be returned\"";
+
-    }
+  // Check the password and update the session on success.
-  ];
+  // Requires that the user is already checked, either in the previous or the same request.
-  optional CheckWebAuthN web_auth_n = 3 [
+  // On successful password check, the session's `factors` field will be updated with a `password` factor,
-    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+  // containing the verification time.
-      description: "\"Checks the public key credential issued by the WebAuthN client. Requires that the user is already checked and a WebAuthN challenge to be requested, in any previous request.\"";
+  // On failed password check id: "COMMAND-3M0fs" wll be returned.
-    }
+  // On user locked out id: "COMMAND-JLK35"/"COMMAND-SFA3t" will be returned.
-  ];
+  optional CheckPassword password = 2;
-  optional CheckIDPIntent idp_intent = 4 [
+
-    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+  // Check the public key credential issued by the WebAuthN client.
-      description: "\"Checks the IDP intent. Requires that the userlink is already checked and a successful idp intent.\"";
+  // Requires that the user is already checked and a WebAuthN challenge to be requested,
-    }
+  // in any previous request.
-  ];
+  // On successful WebAuthN check, the session's `factors` field will be updated with a `webauthn` factor,
-  optional CheckTOTP totp = 5 [
+  // containing the verification time and if the user presence was verified.
-    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+  optional CheckWebAuthN web_auth_n = 3;
-      description: "\"Checks the Time-based One-Time Password and updates the session on success. Requires that the user is already checked, either in the previous or the same request.\"";
+
-    }
+  // Check the IDP intent and update the session on success.
-  ];
+  // Requires that the user is already checked and an IDP intent succeeded and has not expired yet.
-  optional CheckOTP otp_sms = 6 [
+  // Note that the IDP intent must be either matching the same user as checked in the session,
-    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+  // or there must not be an external IDP linked to the intent's user.
-      description: "\"Checks the One-Time Password sent over SMS and updates the session on success. Requires that the user is already checked, either in the previous or the same request.\"";
+  // On successful IDP intent check, the session's `factors` field will be updated with an `intent` factor,
-    }
+  // containing the verification time.
-  ];
+  optional CheckIDPIntent idp_intent = 4;
-  optional CheckOTP otp_email = 7 [
+
-    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+  // Check the Time-based One-Time Password and update the session on success.
-      description: "\"Checks the One-Time Password sent over Email and updates the session on success. Requires that the user is already checked, either in the previous or the same request.\"";
+  // Requires that the user is already checked, either in the previous or the same request.
-    }
+  // On successful TOTP check, the session's `factors` field will be updated with a `totp` factor,
-  ];
+  // containing the verification time.
+  optional CheckTOTP totp = 5;
+
+  // Check the One-Time Password sent over SMS and update the session on success.
+  // Requires that the user is already checked, either in the previous or the same request.
+  // On successful OTP SMS check, the session's `factors` field will be updated with an `otp` factor,
+  // containing the verification time.
+  // Note that the OTP code is valid for a single use only and will be invalidated after a successful check.
+  optional CheckOTP otp_sms = 6;
+
+  // Check the One-Time Password sent over Email and update the session on success.
+  // Requires that the user is already checked, either in the previous or the same request.
+  // On successful OTP Email check, the session's `factors` field will be updated with an `otp` factor,
+  // containing the verification time.
+  // Note that the OTP code is valid for a single use only and will be invalidated after a successful check.
+  optional CheckOTP otp_email = 7;
 }
 
 message CheckUser {
+  // Search the user either by its user ID or login name.
   oneof search {
+    option (validate.required) = true;
+
+    // The unique identifier of the user to be checked.
     string user_id = 1 [
       (validate.rules).string = {min_len: 1, max_len: 200},
+      (google.api.field_behavior) = REQUIRED,
       (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
         min_length: 1;
         max_length: 200;
         example: "\"d654e6ba-70a3-48ef-a95d-37c8d8a7901a\"";
       }
     ];
+
+    // The login name of the user to be checked. It will search case insensitive.
+    // Note this only checks for the computed login name and not for any organization scoped usernames.
+    // Also note that it will not check for emails or phone numbers, even if the corresponding
+    // setting is enabled. Use the user service ListUsers method to find a user by email or phone number first
+    // to obtain the user ID or login name.
     string login_name = 2 [
       (validate.rules).string = {min_len: 1, max_len: 200},
+      (google.api.field_behavior) = REQUIRED,
       (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
         min_length: 1;
         max_length: 200;
@@ -431,8 +571,10 @@ message CheckUser {
 }
 
 message CheckPassword {
+  // The password of the user to be checked.
   string password = 1 [
     (validate.rules).string = {min_len: 1, max_len: 200},
+    (google.api.field_behavior) = REQUIRED,
     (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
       min_length: 1;
       max_length: 200;
@@ -442,11 +584,11 @@ message CheckPassword {
 }
 
 message CheckWebAuthN {
+  // The JSON representation of the public key credential issued by the WebAuthN client.
   google.protobuf.Struct credential_assertion_data = 1 [
     (validate.rules).message.required = true,
     (google.api.field_behavior) = REQUIRED,
     (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
-      description: "JSON representation of public key credential issued by the webAuthN client";
       min_length: 55;
       max_length: 1048576; //1 MB
     }
@@ -454,19 +596,22 @@ message CheckWebAuthN {
 }
 
 message CheckIDPIntent {
+  // The ID of the idp intent, previously returned on the success response of the IDP callback.
   string idp_intent_id = 1 [
     (validate.rules).string = {min_len: 1, max_len: 200},
+    (google.api.field_behavior) = REQUIRED,
     (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
-      description: "ID of the idp intent, previously returned on the success response of the IDP callback"
       min_length: 1;
       max_length: 200;
       example: "\"d654e6ba-70a3-48ef-a95d-37c8d8a7901a\"";
     }
   ];
+
+  // The token of the idp intent, previously returned on the success response of the IDP callback.
   string idp_intent_token = 2 [
     (validate.rules).string = {min_len: 1, max_len: 200},
+    (google.api.field_behavior) = REQUIRED,
     (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
-      description: "token of the idp intent, previously returned on the success response of the IDP callback"
       min_length: 1;
       max_length: 200;
       example: "\"SJKL3ioIDpo342ioqw98fjp3sdf32wahb=\"";
@@ -475,8 +620,10 @@ message CheckIDPIntent {
 }
 
 message CheckTOTP {
+  // The Time-based One-Time Password generated by the user's TOTP authenticator app.
   string code = 1 [
     (validate.rules).string = {min_len: 6, max_len: 6},
+    (google.api.field_behavior) = REQUIRED,
     (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
       min_length: 6;
       max_length: 6;
@@ -486,8 +633,10 @@ message CheckTOTP {
 }
 
 message CheckOTP {
+  // The One-Time Password sent over SMS or Email of the user to be checked.
   string code = 1 [
     (validate.rules).string = {min_len: 1},
+    (google.api.field_behavior) = REQUIRED,
     (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
       min_length: 1;
       example: "\"3237642\"";

proto/zitadel/session/v2beta/session_service.proto

@@ -104,9 +104,12 @@ option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_swagger) = {
   }
 };
 
+// Deprecated: use session service v2 instead. This service will be removed in the next major version of ZITADEL.
 service SessionService {
 
   // Search sessions
+  //
+  // Deprecated: please move to the corresponding endpoint under session service v2. This endpoint will be removed with the next major version of ZITADEL.
   rpc ListSessions (ListSessionsRequest) returns (ListSessionsResponse) {
     option (google.api.http) = {
       post: "/v2beta/sessions/search"
@@ -120,6 +123,7 @@ service SessionService {
     };
 
     option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
+      deprecated: true;
       summary: "Search sessions";
       description: "Search for sessions"
       responses: {
@@ -143,6 +147,8 @@ service SessionService {
   }
 
   // GetSession a session
+  //
+  // Deprecated: please move to the corresponding endpoint under session service v2. This endpoint will be removed with the next major version of ZITADEL.
   rpc GetSession (GetSessionRequest) returns (GetSessionResponse) {
     option (google.api.http) = {
       get: "/v2beta/sessions/{session_id}"
@@ -155,6 +161,7 @@ service SessionService {
     };
 
     option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
+      deprecated: true;
       summary: "Get a session";
       description: "Get a session and all its information like the time of the user or password verification"
       responses: {
@@ -167,6 +174,8 @@ service SessionService {
   }
 
   // Create a new session
+  //
+  // Deprecated: please move to the corresponding endpoint under session service v2. This endpoint will be removed with the next major version of ZITADEL.
   rpc CreateSession (CreateSessionRequest) returns (CreateSessionResponse) {
     option (google.api.http) = {
       post: "/v2beta/sessions"
@@ -183,6 +192,7 @@ service SessionService {
     };
 
     option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
+      deprecated: true;
       summary: "Create a new session";
       description: "Create a new session. A token will be returned, which is required for further updates of the session."
       responses: {
@@ -195,6 +205,8 @@ service SessionService {
   }
 
   // Update a session
+  //
+  // Deprecated: please move to the corresponding endpoint under session service v2. This endpoint will be removed with the next major version of ZITADEL.
   rpc SetSession (SetSessionRequest) returns (SetSessionResponse) {
     option (google.api.http) = {
       patch: "/v2beta/sessions/{session_id}"
@@ -208,6 +220,7 @@ service SessionService {
     };
 
     option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
+      deprecated: true;
       summary: "Update an existing session";
       description: "Update an existing session with new information."
       responses: {
@@ -220,6 +233,8 @@ service SessionService {
   }
 
   // Terminate a session
+  //
+  // Deprecated: please move to the corresponding endpoint under session service v2. This endpoint will be removed with the next major version of ZITADEL.
   rpc DeleteSession (DeleteSessionRequest) returns (DeleteSessionResponse) {
     option (google.api.http) = {
       delete: "/v2beta/sessions/{session_id}"
@@ -233,6 +248,7 @@ service SessionService {
     };
 
     option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
+      deprecated: true;
       summary: "Terminate an existing session";
       description: "Terminate your own session or if granted any other session."
       responses: {

proto/zitadel/user/v2beta/user_service.proto

@@ -108,6 +108,7 @@ option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_swagger) = {
   }
 };
 
+// Deprecated: use user service v2 instead. This service will be removed in the next major version of ZITADEL.
 service UserService {
 
   // Create a new human user

proto/zitadel/webkey/v2/key.proto

@@ -27,20 +27,24 @@ message WebKey {
       example: "\"69629012906488334\"";
     }
   ];
+
   // The timestamp of the key creation.
   google.protobuf.Timestamp creation_date = 2 [
     (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
       example: "\"2024-12-18T07:50:47.492Z\"";
     }
   ];
+
   // The timestamp of the last change to the key (e.g. creation, activation, deactivation).
   google.protobuf.Timestamp change_date = 3 [
     (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
       example: "\"2025-01-23T10:34:18.051Z\"";
     }
   ];
+
   // State of the key
   State state = 4;
+
   // Configured type of the key (either RSA, ECDSA or ED25519)
   oneof key {
     RSA rsa = 5;
@@ -57,7 +61,8 @@ message RSA {
       default: "RSA_BITS_2048";
     }
   ];
-  // Signing algrithm used. Default is SHA256.
+
+  // Signing algorithm used. Default is SHA256.
   RSAHasher hasher = 2 [
     (validate.rules).enum = {defined_only: true, not_in: [0]},
     (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {

proto/zitadel/webkey/v2/webkey_service.proto

@@ -117,9 +117,6 @@ service WebKeyService {
   //
   // Required permission:
   //   - `iam.web_key.write`
-  //
-  // Required feature flag:
-  //   - `web_key`
   rpc CreateWebKey(CreateWebKeyRequest) returns (CreateWebKeyResponse) {
     option (zitadel.protoc_gen_zitadel.v2.options) = {
       auth_option: {
@@ -137,9 +134,6 @@ service WebKeyService {
   //
   // Required permission:
   //   - `iam.web_key.write`
-  //
-  // Required feature flag:
-  //   - `web_key`
   rpc ActivateWebKey(ActivateWebKeyRequest) returns (ActivateWebKeyResponse) {
     option (zitadel.protoc_gen_zitadel.v2.options) = {
       auth_option: {
@@ -180,9 +174,6 @@ service WebKeyService {
   //
   // Required permission:
   //   - `iam.web_key.delete`
-  //
-  // Required feature flag:
-  //   - `web_key`
   rpc DeleteWebKey(DeleteWebKeyRequest) returns (DeleteWebKeyResponse) {
     option (google.api.http) = {
       delete: "/v2/web_keys/{id}"
@@ -216,9 +207,6 @@ service WebKeyService {
   //
   // Required permission:
   //   - `iam.web_key.read`
-  //
-  // Required feature flag:
-  //   - `web_key`
   rpc ListWebKeys(ListWebKeysRequest) returns (ListWebKeysResponse) {
     option (google.api.http) = {
       get: "/v2/web_keys"
@@ -272,6 +260,7 @@ message CreateWebKeyResponse {
       example: "\"69629012906488334\"";
     }
   ];
+
   // The timestamp of the key creation.
   google.protobuf.Timestamp creation_date = 2 [
     (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
@@ -281,6 +270,7 @@ message CreateWebKeyResponse {
 }
 
 message ActivateWebKeyRequest {
+  // The unique identifier of the key to activate.
   string id = 1 [
     (validate.rules).string = {min_len: 1, max_len: 200},
     (google.api.field_behavior) = REQUIRED,
@@ -302,6 +292,7 @@ message ActivateWebKeyResponse {
 }
 
 message DeleteWebKeyRequest {
+  // The unique identifier of the key to delete.
   string id = 1 [
     (validate.rules).string = {min_len: 1, max_len: 200},
     (google.api.field_behavior) = REQUIRED,

proto/zitadel/webkey/v2beta/webkey_service.proto

@@ -16,7 +16,7 @@ option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_swagger) = {
   info: {
     title: "Web key Service";
     version: "2.0-beta";
-    description: "This API is intended to manage web keys for a ZITADEL instance, used to sign and validate OIDC tokens. This service is in beta state. It can AND will continue breaking until a stable version is released.\n\nThe public key endpoint (outside of this service) is used to retrieve the public keys of the active and inactive keys.\n\nPlease make sure to enable the `web_key` feature flag on your instance to use this service.";
+    description: "This API is intended to manage web keys for a ZITADEL instance, used to sign and validate OIDC tokens. This service is in beta state. It can AND will continue breaking until a stable version is released.\n\nThe public key endpoint (outside of this service) is used to retrieve the public keys of the active and inactive keys.\n\nDeprecated: use webkey service v2 instead. This service will be removed in the next major version of ZITADEL.";
     contact:{
       name: "ZITADEL"
       url: "https://zitadel.com"
@@ -104,10 +104,12 @@ option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_swagger) = {
 // The service provides methods to create, activate, delete and list web keys.
 // The public key endpoint (outside of this service) is used to retrieve the public keys of the active and inactive keys.
 //
-// Please make sure to enable the `web_key` feature flag on your instance to use this service.
+// Deprecated: use webkey service v2 instead. This service will be removed in the next major version of ZITADEL.
 service WebKeyService {
   // Create Web Key
   //
+  // Deprecated: please move to the corresponding endpoint under oidc service v2. This endpoint will be removed with the next major version of ZITADEL.
+  //
   // Generate a private and public key pair. The private key can be used to sign OIDC tokens after activation.
   // The public key can be used to validate OIDC tokens.
   // The newly created key will have the state `STATE_INITIAL` and is published to the public key endpoint.
@@ -117,9 +119,6 @@ service WebKeyService {
   //
   // Required permission:
   //   - `iam.web_key.write`
-  //
-  // Required feature flag:
-  //   - `web_key`
   rpc CreateWebKey(CreateWebKeyRequest) returns (CreateWebKeyResponse) {
     option (google.api.http) = {
       post: "/v2beta/web_keys"
@@ -133,6 +132,7 @@ service WebKeyService {
     };
 
     option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
+      deprecated: true;
       responses: {
         key: "200"
         value: {
@@ -150,6 +150,8 @@ service WebKeyService {
 
   // Activate Web Key
   //
+  // Deprecated: please move to the corresponding endpoint under oidc service v2. This endpoint will be removed with the next major version of ZITADEL.
+  //
   // Switch the active signing web key. The previously active key will be deactivated.
   // Note that the JWKs OIDC endpoint returns a cacheable response.
   // Therefore it is not advised to activate a key that has been created within the cache duration (default is 5min),
@@ -157,9 +159,6 @@ service WebKeyService {
   //
   // Required permission:
   //   - `iam.web_key.write`
-  //
-  // Required feature flag:
-  //   - `web_key`
   rpc ActivateWebKey(ActivateWebKeyRequest) returns (ActivateWebKeyResponse) {
     option (google.api.http) = {
       post: "/v2beta/web_keys/{id}/activate"
@@ -172,18 +171,13 @@ service WebKeyService {
     };
 
     option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
+      deprecated: true;
       responses: {
         key: "200"
         value: {
           description: "Web key activated successfully.";
         }
       };
-      responses: {
-        key: "400"
-        value: {
-          description: "The feature flag `web_key` is not enabled.";
-        }
-      };
       responses: {
         key: "404"
         value: {
@@ -195,6 +189,8 @@ service WebKeyService {
 
   // Delete Web Key
   //
+  // Deprecated: please move to the corresponding endpoint under oidc service v2. This endpoint will be removed with the next major version of ZITADEL.
+  //
   // Delete a web key pair. Only inactive keys can be deleted. Once a key is deleted,
   // any tokens signed by this key will be invalid.
   // Note that the JWKs OIDC endpoint returns a cacheable response.
@@ -204,9 +200,6 @@ service WebKeyService {
   //
   // Required permission:
   //   - `iam.web_key.delete`
-  //
-  // Required feature flag:
-  //   - `web_key`
   rpc DeleteWebKey(DeleteWebKeyRequest) returns (DeleteWebKeyResponse) {
     option (google.api.http) = {
       delete: "/v2beta/web_keys/{id}"
@@ -219,30 +212,24 @@ service WebKeyService {
     };
 
     option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
+      deprecated: true;
       responses: {
         key: "200"
         value: {
           description: "Web key deleted successfully.";
         }
       };
-      responses: {
-        key: "400"
-        value: {
-          description: "The feature flag `web_key` is not enabled or the web key is currently active.";
-        }
-      };
     };
   }
 
   // List Web Keys
   //
+  // Deprecated: please move to the corresponding endpoint under oidc service v2. This endpoint will be removed with the next major version of ZITADEL.
+  //
   // List all web keys and their states.
   //
   // Required permission:
   //   - `iam.web_key.read`
-  //
-  // Required feature flag:
-  //   - `web_key`
   rpc ListWebKeys(ListWebKeysRequest) returns (ListWebKeysResponse) {
     option (google.api.http) = {
       get: "/v2beta/web_keys"
@@ -255,18 +242,13 @@ service WebKeyService {
     };
 
     option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
+      deprecated: true;
       responses: {
         key: "200"
         value: {
           description: "List of all web keys.";
         }
       };
-      responses: {
-        key: "400"
-        value: {
-          description: "The feature flag `web_key` is not enabled.";
-        }
-      };
     };
   }
 }