align with api design

proto/zitadel/authorizations/v2beta/authorization.proto

@@ -2,9 +2,12 @@ syntax = "proto3";
 
 package zitadel.authorizations.v2beta;
 
+import "protoc-gen-openapiv2/options/annotations.proto";
 import "google/protobuf/timestamp.proto";
 import "validate/validate.proto";
-import "zitadel/object/v2/object.proto";
+
+import "zitadel/filter/v2/filter.proto";
+import "zitadel/filter/v2beta/filter.proto";
 
 option go_package = "github.com/zitadel/zitadel/pkg/grpc/authorizations/v2beta;authorizations";
 
@@ -15,42 +18,35 @@ message Authorization {
       example: "\"69629012906488334\"";
     }
   ];
+  // Project ID is the ID of the project - owned or granted - the user is authorized for.
+  string project_id = 2 [(validate.rules).string = {
+    min_len: 1
+    max_len: 200
+  }];
   // The unique identifier of the organization the authorization belongs to.
-  string organization_id = 2 [
+  string organization_id = 3 [
     (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
       example: "\"69629012906488334\"";
     }
   ];
   // CreationDate is the timestamp when the authorization was created.
-  google.protobuf.Timestamp creation_date = 3 [
+  google.protobuf.Timestamp creation_date = 4 [
     (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
       example: "\"2024-12-18T07:50:47.492Z\"";
     }
   ];
   // ChangeDate is the timestamp when the authorization was last updated.
   // In case the authorization was not updated, this field is equal to the creation date.
-  google.protobuf.Timestamp change_date = 4 [
+  google.protobuf.Timestamp change_date = 5 [
     (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
       example: "\"2025-01-23T10:34:18.051Z\"";
     }
   ];
   // State is the current state of the authorization.
-  State state = 5;
-  User user = 6;
-  // The granted organization ID is returned If the user is authorized to a project that was granted by another organization.
-  optional string granted_organization_id = 7 [
-    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
-      example: "\"69629023906488334\""
-    }
-  ];
-  // The granted organization name is returned If the user is authorized to a project that was granted by another organization.
-  optional string granted_organization_name = 8 [
-    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
-      example: "\"Some Organization\""
-    }
-  ];
+  State state = 6;
+  User user = 7;
   // Roles contains the roles the user was granted for the project.
-  repeated Role roles = 9;
+  repeated Role roles = 8;
 }
 
 enum State {
@@ -84,90 +80,44 @@ message Role {
   string display_name = 2;
 }
 
-message AuthorizationQuery {
-  oneof query {
+message AuthorizationsSearchFilter {
+  oneof filter {
     option (validate.required) = true;
 
-    // Search for authorizations by their ID.
-    AuthorizationIDQuery authorization_id = 1;
+    // Search for authorizations by their IDs.
+    zitadel.filter.v2beta.InIDsFilter authorization_ids = 1;
+    // Search for an organizations authorizations by its ID.
+    zitadel.filter.v2.IDFilter organization_id = 2;
     // Search for authorizations by their creation date.
-    CreationDateQuery creation_date = 2;
+    zitadel.filter.v2.TimestampFilter creation_date = 3;
     // Search for authorizations by their change date.
-    ChangeDateQuery change_date = 3;
+    zitadel.filter.v2.TimestampFilter change_date = 4;
     // Search for authorizations by their state.
-    StateQuery state = 4;
+    StateQuery state = 5;
     // Search for authorizations by the ID of the user who was granted the authorization.
-    UserIDQuery user_id = 5;
+    zitadel.filter.v2.IDFilter user_id = 6;
     // Search for authorizations by the ID of the organisation the user is part of.
-    UserOrganizationIDQuery user_organization_id = 6;
+    zitadel.filter.v2.IDFilter user_organization_id = 7;
     // Search for authorizations by the preferred login name of the granted user.
-    UserPreferredLoginNameQuery user_preferred_login_name = 7;
+    UserPreferredLoginNameQuery user_preferred_login_name = 8;
     // Search for authorizations by the public display name of the granted user.
-    UserDisplayNameQuery user_display_name = 8;
+    UserDisplayNameQuery user_display_name = 9;
     // Search for authorizations by the ID of the project the user was granted the authorization for.
     // This will also include authorizations granted for project grants of the same project.
-    ProjectIDQuery project_id = 9;
+    zitadel.filter.v2.IDFilter project_id = 10;
     // Search for authorizations by the name of the project the user was granted the authorization for.
     // This will also include authorizations granted for project grants of the same project.
-    ProjectNameQuery project_name = 10;
-    // Search for authorizations by the ID of the project grant the user was granted the authorization for.
-    ProjectGrantIDQuery project_grant_id = 11;
-    // Search for authorizations by the ID of the organization the authorization was granted for.
-    // This can either be the organization the project or the project grant is part of.
-    OrganizationIDQuery granted_organization_id = 12;
-    OrganizationNameQuery granted_organization_name = 13;
+    ProjectNameQuery project_name = 11;
     // Search for authorizations by the key of the role the user was granted.
-    RoleKeyQuery role_key = 14;
+    RoleKeyQuery role_key = 12;
   }
 }
 
-message AuthorizationIDQuery {
-  string id = 1 [(validate.rules).string = {
-    min_len: 1
-    max_len: 200
-  }];
-}
-
-message CreationDateQuery {
-  // Specify the creation date of the authorization to search for.
-  google.protobuf.Timestamp creation_date = 1;
-  // Specify the method to search for the creation date. Default is EQUAL.
-  // For example, to search for all authorizations created after a specific date, use GREATER_THAN.
-  // To search for all authorizations created before a specific date, use LESS_THAN.
-  zitadel.object.v2.TimestampQueryMethod method = 2 [(validate.rules).enum.defined_only = true];
-}
-
-message ChangeDateQuery {
-  // Specify the change date of the authorization to search for.
-  google.protobuf.Timestamp change_date = 1;
-  // Specify the method to search for the change date. Default is EQUAL.
-  // For example, to search for all authorizations changed after a specific date, use GREATER_THAN.
-  // To search for all authorizations changed before a specific date, use LESS_THAN.
-  zitadel.object.v2.TimestampQueryMethod method = 2 [(validate.rules).enum.defined_only = true];
-}
-
 message StateQuery {
   // Specify the state of the authorization to search for.
   State state = 1 [(validate.rules).enum = {defined_only: true, not_in: [0]}];
 }
 
-message UserIDQuery {
-  // Specify the ID of the user who was granted the authorization to search for.
-  string id = 1 [(validate.rules).string = {
-    min_len: 1
-    max_len: 200
-  }];
-}
-
-message UserOrganizationIDQuery {
-  // Specify the ID of the organization the user is part of to search for.
-  // Note that this might not be the organization the authorization was granted for.
-  string id = 1 [(validate.rules).string = {
-    min_len: 1
-    max_len: 200
-  }];
-}
-
 message UserPreferredLoginNameQuery {
   // Specify the preferred login name of the granted user to search for.
   string login_name = 1 [(validate.rules).string = {
@@ -177,7 +127,7 @@ message UserPreferredLoginNameQuery {
   // Specify the method to search for the preferred login name. Default is EQUAL.
   // For example, to search for all authorizations granted to a user with
   // a preferred login name containing a specific string, use CONTAINS or CONTAINS_IGNORE_CASE.
-  zitadel.object.v2.TextQueryMethod method = 2 [(validate.rules).enum.defined_only = true];
+  zitadel.filter.v2.TextFilterMethod method = 2 [(validate.rules).enum.defined_only = true];
 }
 
 message UserDisplayNameQuery {
@@ -189,16 +139,7 @@ message UserDisplayNameQuery {
   // Specify the method to search for the display name. Default is EQUAL.
   // For example, to search for all authorizations granted to a user with
   // a display name containing a specific string, use CONTAINS or CONTAINS_IGNORE_CASE.
-  zitadel.object.v2.TextQueryMethod method = 2 [(validate.rules).enum.defined_only = true];
-}
-
-message ProjectIDQuery {
-  // Specify the ID of the project the user was granted the authorization for to search for.
-  // Note that this will also include authorizations granted for project grants of the same project.
-  string id = 1 [(validate.rules).string = {
-    min_len: 1
-    max_len: 200
-  }];
+  zitadel.filter.v2.TextFilterMethod method = 2 [(validate.rules).enum.defined_only = true];
 }
 
 message ProjectNameQuery {
@@ -208,24 +149,7 @@ message ProjectNameQuery {
   // Specify the method to search for the project name. Default is EQUAL.
   // For example, to search for all authorizations granted on a project with
   // a name containing a specific string, use CONTAINS or CONTAINS_IGNORE_CASE.
-  zitadel.object.v2.TextQueryMethod method = 2 [(validate.rules).enum.defined_only = true];
-}
-
-message ProjectGrantIDQuery {
-  // Specify the ID of the project grant the user was granted the authorization for to search for.
-  string id = 1 [(validate.rules).string = {
-    min_len: 1
-    max_len: 200
-  }];
-}
-
-message OrganizationIDQuery {
-  // Specify the ID of the organization the authorization was granted for to search for.
-  // This can either be the organization the project or the project grant is part of.
-  string id = 1 [(validate.rules).string = {
-    min_len: 1
-    max_len: 200
-  }];
+  zitadel.filter.v2.TextFilterMethod method = 2 [(validate.rules).enum.defined_only = true];
 }
 
 message OrganizationNameQuery {
@@ -235,7 +159,7 @@ message OrganizationNameQuery {
   // Specify the method to search for the organization name. Default is EQUAL.
   // For example, to search for all authorizations with an organization name containing a specific string,
   // use CONTAINS or CONTAINS_IGNORE_CASE.
-  zitadel.object.v2.TextQueryMethod method = 2 [(validate.rules).enum.defined_only = true];
+  zitadel.filter.v2.TextFilterMethod method = 2 [(validate.rules).enum.defined_only = true];
 }
 
 message RoleKeyQuery {
@@ -244,17 +168,16 @@ message RoleKeyQuery {
   // Specify the method to search for the role key. Default is EQUAL.
   // For example, to search for all authorizations starting with a specific role key,
   // use STARTS_WITH or STARTS_WITH_IGNORE_CASE.
-  zitadel.object.v2.TextQueryMethod method = 2 [(validate.rules).enum.defined_only = true];
+  zitadel.filter.v2.TextFilterMethod method = 2 [(validate.rules).enum.defined_only = true];
 }
 
-message AndQuery {
-  repeated AuthorizationQuery queries = 1;
-}
-
-message OrQuery {
-  repeated AuthorizationQuery queries = 1;
-}
-
-message NotQuery {
-  AuthorizationQuery query = 1;
+enum AuthorizationFieldName {
+  AUTHORIZATION_FIELD_NAME_UNSPECIFIED = 0;
+  AUTHORIZATION_FIELD_NAME_CREATED_DATE = 1;
+  AUTHORIZATION_FIELD_NAME_CHANGED_DATE = 2;
+  AUTHORIZATION_FIELD_NAME_ID = 3;
+  AUTHORIZATION_FIELD_NAME_USER_ID = 4;
+  AUTHORIZATION_FIELD_NAME_PROJECT_ID = 5;
+  AUTHORIZATION_FIELD_NAME_ORGANIZATION_ID = 6;
+  AUTHORIZATION_FIELD_NAME_USER_ORGANIZATION_ID = 7;
 }

proto/zitadel/authorizations/v2beta/authorization_service.proto

@@ -2,10 +2,14 @@ syntax = "proto3";
 
 package zitadel.authorizations.v2beta;
 
+import "protoc-gen-openapiv2/options/annotations.proto";
 import "google/protobuf/timestamp.proto";
 import "validate/validate.proto";
+import "google/api/annotations.proto";
+
+import "zitadel/protoc_gen_zitadel/v2/options.proto";
 import "zitadel/authorizations/v2beta/authorization.proto";
-import "zitadel/object/v2/object.proto";
+import "zitadel/filter/v2/filter.proto";
 
 option go_package = "github.com/zitadel/zitadel/pkg/grpc/authorizations/v2beta;authorizations";
 
@@ -14,33 +18,160 @@ option go_package = "github.com/zitadel/zitadel/pkg/grpc/authorizations/v2beta;a
 // For managing permissions and roles for ZITADEL internal resources, like organizations, projects,
 // users, etc., please use the InternalPermissionsService.
 service AuthorizationsService {
+
+  // List Authorizations
+  //
   // ListAuthorizations returns all authorizations matching the request and necessary permissions.
   //
   // Required permissions:
   //   - "user.grant.read"
   //   - no permissions required for listing own authorizations
-  rpc ListAuthorizations(ListAuthorizationsRequest) returns (ListAuthorizationsResponse) {}
+  rpc ListAuthorizations(ListAuthorizationsRequest) returns (ListAuthorizationsResponse) {
+    option (google.api.http) = {
+      // The only reason why it is used here is to avoid a conflict with the ListUsers endpoint, which already handles POST /v2/users.
+      post: "/v2beta/authorizations/search"
+      body: "*"
+    };
 
+    option (zitadel.protoc_gen_zitadel.v2.options) = {
+      auth_option: {
+        permission: "authenticated"
+      }
+    };
+
+    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
+      responses: {
+        key: "200";
+        value: {
+          description: "A list of all authorizations matching the query";
+        };
+      };
+      responses: {
+        key: "400";
+        value: {
+          description: "invalid list query";
+        };
+      };
+    };
+  }
+
+  // Get Authorization
+  //
   // GetAuthorization returns the authorization by its ID.
   //
   // Required permissions:
   //   - "user.grant.read"
   //   - no permissions required for getting own authorization
-  rpc GetAuthorization(GetAuthorizationRequest) returns (GetAuthorizationResponse) {}
+  rpc GetAuthorization(GetAuthorizationRequest) returns (GetAuthorizationResponse) {
+    option (google.api.http) = {
+      get: "/v2beta/authorizations/{id}"
+    };
+    option (zitadel.protoc_gen_zitadel.v2.options) = {
+      auth_option: {
+        permission: "authenticated"
+      }
+    };
+    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
+      responses: {
+        key: "200";
+        value: {
+          description: "The authorization with the given ID";
+        };
+      };
+      responses: {
+        key: "404";
+        value: {
+          description: "authorization not found";
+        };
+      };
+    };
+  }
 
-  // CreateAuthorization creates a new authorization for a user in a project or project grant.
+  // Create Authorization
+  //
+  // CreateAuthorization creates a new authorization for a user in an owned or granted project.
   //
   // Required permissions:
   //   - "user.grant.write"
-  rpc CreateAuthorization(CreateAuthorizationRequest) returns (CreateAuthorizationResponse) {}
+  rpc CreateAuthorization(CreateAuthorizationRequest) returns (CreateAuthorizationResponse) {
+    option (google.api.http) = {
+      post: "/v2beta/authorizations"
+      body: "*"
+    };
 
+    option (zitadel.protoc_gen_zitadel.v2.options) = {
+      auth_option: {
+        permission: "authenticated"
+      }
+    };
+
+    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
+      responses: {
+        key: "200";
+        value: {
+          description: "The newly created authorization";
+        };
+      };
+      responses: {
+        key: "400";
+        value: {
+          description: "invalid create request";
+        };
+      };
+      responses: {
+        key: "409"
+        value: {
+          description: "The authorization already exists.";
+          schema: {
+            json_schema: {
+              ref: "#/definitions/rpcStatus";
+            };
+          };
+        }
+      };
+    };
+  }
+
+  // Update Authorization
+  //
   // UpdateAuthorization updates the authorization.
   //
   // Note that any role keys previously granted to the user and not present in the request will be revoked.
   //
   // Required permissions:
   //   - "user.grant.write"
-  rpc UpdateAuthorization(UpdateAuthorizationRequest) returns (UpdateAuthorizationResponse) {}
+  rpc UpdateAuthorization(UpdateAuthorizationRequest) returns (UpdateAuthorizationResponse) {
+    option (google.api.http) = {
+      patch: "/v2beta/authorizations/{id}"
+      body: "*"
+    };
+
+    option (zitadel.protoc_gen_zitadel.v2.options) = {
+      auth_option: {
+        permission: "authenticated"
+      }
+    };
+
+    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
+      responses: {
+        key: "200";
+        value: {
+          description: "OK";
+        };
+      };
+      responses: {
+        key: "404";
+        value: {
+          description: "Authorization or one of the roles do not exist.";
+          schema: {
+            json_schema: {
+              ref: "#/definitions/rpcStatus";
+            };
+          };
+        }
+      }
+    };
+  }
 
   // DeleteAuthorization deletes the authorization.
   //
@@ -50,28 +181,69 @@ service AuthorizationsService {
   //
   // Required permissions:
   //   - "user.grant.delete"
-  rpc DeleteAuthorization(DeleteAuthorizationRequest) returns (DeleteAuthorizationResponse) {}
+  rpc DeleteAuthorization(DeleteAuthorizationRequest) returns (DeleteAuthorizationResponse) {
+    option (google.api.http) = {
+      delete: "/v2beta/authorizations/{id}"
+    };
+
+    option (zitadel.protoc_gen_zitadel.v2.options) = {
+      auth_option: {
+        permission: "authenticated"
+      }
+    };
+
+    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
+      responses: {
+        key: "200";
+        value: {
+          description: "The authorization was deleted successfully.";
+        };
+      };
+      responses: {
+        key: "404";
+        value: {
+          description: "Authorization not found.";
+          schema: {
+            json_schema: {
+              ref: "#/definitions/rpcStatus";
+            };
+          };
+        };
+      };
+    };
+  }
 }
 
 message ListAuthorizationsRequest {
   // Paginate through the results using a limit, offset and sorting.
-  zitadel.object.v2.ListQuery query = 1;
-  // Filter the authorizations to be returned.
-  repeated AuthorizationQuery queries = 2;
+  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 AuthorizationFieldName sorting_column = 2 [
+    (validate.rules).enum = {defined_only: true},
+    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+      default: "\"AUTHORIZATION_FIELD_NAME_CREATED_DATE\""
+    }
+  ];
+  // Define the criteria to query for.
+  repeated AuthorizationsSearchFilter filters = 3;
 }
 
 message ListAuthorizationsResponse {
   // Details contains the pagination information.
-  zitadel.object.v2.ListDetails details = 1;
-  repeated Authorization authorizations = 2;
+  zitadel.filter.v2.PaginationResponse pagination = 1;
+  repeated Authorization result = 2;
 }
 
 message GetAuthorizationRequest {
   // ID is the unique identifier of the authorization.
-  string id = 1 [(validate.rules).string = {
-    min_len: 1
-    max_len: 200
-  }];
+  string 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;
+      example: "\"163840776835432345\"";
+    }
+  ];
 }
 
 message GetAuthorizationResponse {
@@ -80,69 +252,113 @@ message GetAuthorizationResponse {
 
 message CreateAuthorizationRequest {
   // UserID is the ID of the user who should be granted the authorization.
-  string user_id = 1 [(validate.rules).string = {
-    min_len: 1
-    max_len: 200
-  }];
-  // Project ID is the ID of the project - owned or granted - the user should be authorized for.
-  string project_id = 2 [(validate.rules).string = {
-    min_len: 1
-    max_len: 200
-  }];
-  // RoleKeys are the keys of the roles the user should be granted.
-  repeated string role_keys = 3 [(validate.rules).repeated = {
-    unique: true
-    items: {
-      string: {
-        min_len: 1
-        max_len: 200
-      }
+  string user_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;
+      example: "\"163840776835432345\"";
     }
-  }];
+  ];
+  // Project ID is the ID of the owned or granted project the user should be authorized for.
+  string project_id = 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: "\"163840776835432345\"";
+    }
+  ];
+  // RoleKeys are the keys of the roles the user should be granted.
+  repeated string role_keys = 3 [
+    (validate.rules).repeated = {
+      unique: true
+      items: {
+        string: {
+          min_len: 1
+          max_len: 200
+        }
+      }
+    },
+    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+      min_length: 1;
+      max_length: 200;
+      example: "[\"user\",\"admin\"]";
+    }
+  ];
 }
 
 message CreateAuthorizationResponse {
   // ID is the unique identifier of the newly created authorization.
-  string id = 1;
+  string id = 1 [
+    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+      example: "\"69629012906488334\"";
+    }
+  ];
   // CreationDate is the timestamp when the authorization was created.
-  google.protobuf.Timestamp creation_date = 2;
+  google.protobuf.Timestamp creation_date = 2 [
+    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+      example: "\"2025-01-23T10:34:18.051Z\"";
+    }
+  ];
 }
 
 message UpdateAuthorizationRequest {
   // ID is the unique identifier of the authorization.
-  string id = 1 [(validate.rules).string = {
-    min_len: 1
-    max_len: 200
-  }];
+  string 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;
+      example: "\"163840776835432345\"";
+    }
+  ];
   // RoleKeys are the keys of the roles the user should be granted.
   // Note that any role keys previously granted to the user and not present in the list will be revoked.
-  repeated string role_keys = 2 [(validate.rules).repeated = {
-    unique: true
-    items: {
-      string: {
-        min_len: 1
-        max_len: 200
+  repeated string role_keys = 2 [
+    (validate.rules).repeated = {
+      unique: true
+      items: {
+        string: {
+          min_len: 1
+          max_len: 200
+        }
       }
+    },
+    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+      min_length: 1;
+      max_length: 200;
+      example: "[\"user\",\"admin\"]";
     }
-  }];
+  ];
 }
 
 message UpdateAuthorizationResponse {
   // ChangeDate is the timestamp when the authorization was last updated.
-  google.protobuf.Timestamp change_date = 1;
+  google.protobuf.Timestamp change_date = 1 [
+    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+      example: "\"2024-12-18T07:50:47.492Z\"";
+    }
+  ];
 }
 
 message DeleteAuthorizationRequest {
   // ID is the unique identifier of the authorization that should be deleted.
-  string id = 1 [(validate.rules).string = {
-    min_len: 1
-    max_len: 200
-  }];
+  string 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;
+      example: "\"163840776835432345\"";
+    }
+  ];
 }
 
 message DeleteAuthorizationResponse {
   // DeletionDate is the timestamp when the authorization was deleted.
-  // Note that the deletion date is only guaranteed to be set if the deletion was successful during the request.
-  // In case the deletion occurred in a previous request, the deletion date might not be set.
-  google.protobuf.Timestamp deletion_date = 1;
+  google.protobuf.Timestamp deletion_date = 1 [
+    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+      example: "\"2024-12-18T07:50:47.492Z\"";
+    }
+  ];
 }

proto/zitadel/filter/v2/filter.proto

@@ -0,0 +1,99 @@
+syntax = "proto3";
+
+package zitadel.filter.v2;
+
+option go_package = "github.com/zitadel/zitadel/pkg/grpc/filter/v2;filter";
+
+import "google/protobuf/timestamp.proto";
+import "protoc-gen-openapiv2/options/annotations.proto";
+import "validate/validate.proto";
+
+enum TextFilterMethod {
+  TEXT_FILTER_METHOD_EQUALS = 0;
+  TEXT_FILTER_METHOD_EQUALS_IGNORE_CASE = 1;
+  TEXT_FILTER_METHOD_STARTS_WITH = 2;
+  TEXT_FILTER_METHOD_STARTS_WITH_IGNORE_CASE = 3;
+  TEXT_FILTER_METHOD_CONTAINS = 4;
+  TEXT_FILTER_METHOD_CONTAINS_IGNORE_CASE = 5;
+  TEXT_FILTER_METHOD_ENDS_WITH = 6;
+  TEXT_FILTER_METHOD_ENDS_WITH_IGNORE_CASE = 7;
+}
+
+enum ListFilterMethod {
+  LIST_FILTER_METHOD_IN = 0;
+}
+
+enum TimestampFilterMethod {
+  TIMESTAMP_FILTER_METHOD_EQUALS = 0;
+  TIMESTAMP_FILTER_METHOD_AFTER = 1;
+  TIMESTAMP_FILTER_METHOD_AFTER_OR_EQUALS = 2;
+  TIMESTAMP_FILTER_METHOD_BEFORE = 3;
+  TIMESTAMP_FILTER_METHOD_BEFORE_OR_EQUALS = 4;
+}
+
+message PaginationRequest {
+  // Starting point for retrieval, in combination of offset used to query a set list of objects.
+  uint64 offset = 1 [
+    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+      example: "0";
+    }
+  ];
+  // limit is the maximum amount of objects returned. The default is set to 100
+  // with a maximum of 1000 in the runtime configuration.
+  // If the limit exceeds the maximum configured ZITADEL will throw an error.
+  // If no limit is present the default is taken.
+  uint32 limit = 2 [
+    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+      example: "10";
+    }
+  ];
+  // Asc is the sorting order. If true the list is sorted ascending, if false
+  // the list is sorted descending. The default is descending.
+  bool asc = 3 [
+    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+      example: "false";
+    }
+  ];
+}
+
+message PaginationResponse {
+  // Absolute number of objects matching the query, regardless of applied limit.
+  uint64 total_result = 1 [
+    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+      example: "100";
+    }
+  ];
+  // Applied limit from query, defines maximum amount of objects per request, to compare if all objects are returned.
+  uint64 applied_limit = 2 [
+    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+      example: "100";
+    }
+  ];
+}
+
+message IDFilter {
+  // Only return resources that belong to this id.
+  string id = 1 [
+    (validate.rules).string = {max_len: 200},
+    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+      max_length: 200;
+      example: "\"123\"";
+    }
+  ];
+}
+
+message TimestampFilter {
+  // Filter resources by timestamp.
+  google.protobuf.Timestamp timestamp = 1 [
+    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+      example: "\"2024-12-18T07:50:47.492Z\"";
+    }
+  ];
+  // Define which condition the retrieved resources timestamp should match.
+  TimestampFilterMethod method = 2 [
+    (validate.rules).enum.defined_only = true,
+    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+      description: "defines which text equality method is used";
+    }
+  ];
+}