feat: instance requests implementation for resource API (#9830)

<!--
Please inform yourself about the contribution guidelines on submitting a
PR here:
https://github.com/zitadel/zitadel/blob/main/CONTRIBUTING.md#submit-a-pull-request-pr.
Take note of how PR/commit titles should be written and replace the
template texts in the sections below. Don't remove any of the sections.
It is important that the commit history clearly shows what is changed
and why.
Important: By submitting a contribution you agree to the terms from our
Licensing Policy as described here:
https://github.com/zitadel/zitadel/blob/main/LICENSING.md#community-contributions.
-->

# Which Problems Are Solved

These changes introduce resource-based API endpoints for managing
instances and custom domains.

There are 4 types of changes:

- Endpoint implementation: consisting of the protobuf interface and the
implementation of the endpoint. E.g:
606439a172
- (Integration) Tests: testing the implemented endpoint. E.g:
cdfe1f0372
- Fixes: Bugs found during development that are being fixed. E.g:
acbbeedd32
- Miscellaneous: code needed to put everything together or that doesn't
fit any of the above categories. E.g:
529df92abc or
6802cb5468

# How the Problems Are Solved

_Ticked checkboxes indicate that the functionality is complete_

- [x] Instance
  - [x] Create endpoint
  - [x] Create endpoint tests
  - [x] Update endpoint
  - [x] Update endpoint tests
  - [x] Get endpoint
  - [x] Get endpoint tests
  - [x] Delete endpoint
  - [x] Delete endpoint tests
- [x] Custom Domains
  - [x] Add custom domain
  - [x] Add custom domain tests
  - [x] Remove custom domain
  - [x] Remove custom domain tests
  - [x] List custom domains
  - [x] List custom domains tests
- [x] Trusted Domains
  - [x] Add trusted domain
  - [x] Add trusted domain tests
  - [x] Remove trusted domain
  - [x] Remove trusted domain tests
  - [x] List trusted domains
  - [x] List trusted domains tests

# Additional Changes

When looking for instances (through the `ListInstances` endpoint)
matching a given query, if you ask for the results to be order by a
specific column, the query will fail due to a syntax error. This is
fixed in acbbeedd32 . Further explanation
can be found in the commit message

# Additional Context

- Relates to #9452 
- CreateInstance has been excluded:
https://github.com/zitadel/zitadel/issues/9930
- Permission checks / instance retrieval (middleware) needs to be
changed to allow context based permission checks
(https://github.com/zitadel/zitadel/issues/9929), required for
ListInstances

---------

Co-authored-by: Livio Spring <livio.a@gmail.com>

proto/zitadel/admin.proto

@@ -307,6 +307,7 @@ service AdminService {
         };
     }
 
+    // Deprecated: Use [ListCustomDomains](apis/resources/instance_service_v2/instance-service-list-custom-domains.api.mdx) instead to list custom domains
     rpc ListInstanceDomains(ListInstanceDomainsRequest) returns (ListInstanceDomainsResponse) {
         option (google.api.http) = {
             post: "/domains/_search";
@@ -319,10 +320,12 @@ service AdminService {
         option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
             tags: "Instance";
             summary: "List Instance Domains";
-            description: "Returns a list of domains that are configured for this ZITADEL instance. These domains are the URLs where ZITADEL is running."
+            description: "Returns a list of domains that are configured for this ZITADEL instance. These domains are the URLs where ZITADEL is running.";
+            deprecated: true;
         };
     }
 
+    // Deprecated: Use [ListTrustedDomains](apis/resources/instance_service_v2/instance-service-list-trusted-domains.api.mdx) instead to list trusted domains
     rpc ListInstanceTrustedDomains(ListInstanceTrustedDomainsRequest) returns (ListInstanceTrustedDomainsResponse) {
         option (google.api.http) = {
             post: "/trusted_domains/_search";
@@ -335,10 +338,12 @@ service AdminService {
         option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
             tags: "Instance";
             summary: "List Instance Trusted Domains";
-            description: "Returns a list of domains that are configured for this ZITADEL instance. These domains are trusted to be used as public hosts."
+            description: "Returns a list of domains that are configured for this ZITADEL instance. These domains are trusted to be used as public hosts.";
+            deprecated: true;
         };
     }
 
+    // Deprecated: Use [AddTrustedDomain](apis/resources/instance_service_v2/instance-service-add-trusted-domain.api.mdx) instead to add a trusted domain
     rpc AddInstanceTrustedDomain(AddInstanceTrustedDomainRequest) returns (AddInstanceTrustedDomainResponse) {
         option (google.api.http) = {
             post: "/trusted_domains";
@@ -352,10 +357,12 @@ service AdminService {
         option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
             tags: "Instance";
             summary: "Add an Instance Trusted Domain";
-            description: "Returns a list of domains that are configured for this ZITADEL instance. These domains are trusted to be used as public hosts."
+            description: "Returns a list of domains that are configured for this ZITADEL instance. These domains are trusted to be used as public hosts.";
+            deprecated: true;
         };
     }
 
+    // Deprecated: Use [RemoveTrustedDomain](apis/resources/instance_service_v2/instance-service-remove-trusted-domain.api.mdx) instead to remove a trusted domain
     rpc RemoveInstanceTrustedDomain(RemoveInstanceTrustedDomainRequest) returns (RemoveInstanceTrustedDomainResponse) {
         option (google.api.http) = {
             delete: "/trusted_domains/{domain}";
@@ -368,7 +375,8 @@ service AdminService {
         option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
             tags: "Instance";
             summary: "Remove an Instance Trusted Domain";
-            description: "Returns a list of domains that are configured for this ZITADEL instance. These domains are trusted to be used as public hosts."
+            description: "Returns a list of domains that are configured for this ZITADEL instance. These domains are trusted to be used as public hosts.";
+            deprecated: true;
         };
     }
 

proto/zitadel/instance/v2beta/instance.proto

@@ -0,0 +1,192 @@
+syntax = "proto3";
+
+import "protoc-gen-openapiv2/options/annotations.proto";
+import "zitadel/object/v2/object.proto";
+import "validate/validate.proto";
+import "google/protobuf/timestamp.proto";
+
+package zitadel.instance.v2beta;
+
+option go_package = "github.com/zitadel/zitadel/pkg/grpc/instance/v2beta;instance";
+
+message Instance {
+    string id = 1 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            example: "\"69629023906488334\""
+        }
+    ];
+
+    // change_date is the timestamp when the object was changed
+    //
+    // on read: the timestamp of the last event reduced by the projection
+    //
+    // on manipulation: the timestamp of the event(s) added by the manipulation
+    google.protobuf.Timestamp change_date = 2 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            example: "\"2025-01-23T10:34:18.051Z\"";
+        }
+    ];
+
+    google.protobuf.Timestamp creation_date = 3 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            example: "\"2025-01-23T10:34:18.051Z\"";
+        }
+    ];
+    State state = 4 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            description: "current state of the instance";
+        }
+    ];
+    string name = 5 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            example: "\"ZITADEL\"";
+        }
+    ];
+    string version = 6 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            example: "\"1.0.0\"";
+        }
+    ];
+    repeated Domain domains = 7;
+}
+
+enum State {
+    STATE_UNSPECIFIED = 0;
+    STATE_CREATING = 1;
+    STATE_RUNNING = 2;
+    STATE_STOPPING = 3;
+    STATE_STOPPED = 4;
+}
+
+message Domain {
+    string instance_id = 1;
+
+    google.protobuf.Timestamp creation_date = 2 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            example: "\"2025-01-23T10:34:18.051Z\"";
+        }
+    ];
+
+    string domain = 3 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            example: "\"zitadel.com\""
+        }
+    ];
+    bool primary = 4;
+    bool generated = 5;
+}
+
+enum FieldName {
+    FIELD_NAME_UNSPECIFIED = 0;
+    FIELD_NAME_ID = 1;
+    FIELD_NAME_NAME = 2;
+    FIELD_NAME_CREATION_DATE = 3;
+}
+
+message Query {
+    oneof query {
+        option (validate.required) = true;
+
+        IdsQuery id_query = 1;
+        DomainsQuery domain_query = 2;
+    }
+}
+
+message IdsQuery {
+    repeated string ids = 1 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            description: "Instance ID";
+            example: "[\"4820840938402429\",\"4820840938402422\"]"
+        }
+    ];
+}
+
+message DomainsQuery {
+    repeated string domains = 1  [
+        (validate.rules).repeated = {max_items: 20, items: {string: {min_len: 1, max_len: 100}}},
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            max_items: 20;
+            example: "[\"my-instace.zitadel.cloud\", \"auth.custom.com\"]";
+            description: "Return the instances that have the requested domains";
+        }
+    ];
+}
+message DomainSearchQuery {
+    oneof query {
+        option (validate.required) = true;
+
+        DomainQuery domain_query = 1;
+        DomainGeneratedQuery generated_query = 2;
+        DomainPrimaryQuery primary_query = 3;
+    }
+}
+
+message DomainQuery {
+    string domain = 1 [
+        (validate.rules).string = {max_len: 200},
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            max_length: 200;
+            example: "\"zitadel.com\"";
+        }
+    ];
+    zitadel.object.v2.TextQueryMethod method = 2 [
+        (validate.rules).enum.defined_only = true,
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            description: "Defines which text equality method is used";
+        }
+    ];
+}
+
+message DomainGeneratedQuery {
+    bool generated = 1 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            description: "Generated domains";
+        }
+    ];
+}
+
+message DomainPrimaryQuery {
+    bool primary = 1 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            description: "Primary domains";
+        }
+    ];
+}
+
+enum DomainFieldName {
+    DOMAIN_FIELD_NAME_UNSPECIFIED = 0;
+    DOMAIN_FIELD_NAME_DOMAIN = 1;
+    DOMAIN_FIELD_NAME_PRIMARY = 2;
+    DOMAIN_FIELD_NAME_GENERATED = 3;
+    DOMAIN_FIELD_NAME_CREATION_DATE = 4;
+}
+
+message TrustedDomain {
+    string instance_id = 1;
+
+    google.protobuf.Timestamp creation_date = 2 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            example: "\"2025-01-23T10:34:18.051Z\"";
+        }
+    ];
+
+    string domain = 3 [
+        (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+            example: "\"zitadel.com\""
+        }
+    ];
+}
+
+message TrustedDomainSearchQuery {
+    oneof query {
+        option (validate.required) = true;
+
+        DomainQuery domain_query = 1;
+    }
+}
+
+enum TrustedDomainFieldName {
+    TRUSTED_DOMAIN_FIELD_NAME_UNSPECIFIED = 0;
+    TRUSTED_DOMAIN_FIELD_NAME_DOMAIN = 1;
+    TRUSTED_DOMAIN_FIELD_NAME_CREATION_DATE = 2;
+}

proto/zitadel/instance/v2beta/instance_service.proto

@@ -0,0 +1,648 @@
+syntax = "proto3";
+
+package zitadel.instance.v2beta;
+
+import "validate/validate.proto";
+import "zitadel/object/v2/object.proto";
+import "zitadel/instance/v2beta/instance.proto";
+import "zitadel/filter/v2beta/filter.proto";
+import "protoc-gen-openapiv2/options/annotations.proto";
+import "google/protobuf/empty.proto";
+import "google/api/annotations.proto";
+import "google/api/field_behavior.proto";
+import "google/protobuf/timestamp.proto";
+import "zitadel/protoc_gen_zitadel/v2/options.proto";
+
+option go_package = "github.com/zitadel/zitadel/pkg/grpc/instance/v2beta;instance";
+
+option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_swagger) = {
+  info: {
+    title: "Instance Service";
+    version: "2.0-beta";
+    description: "This API is intended to manage instances in ZITADEL.";
+    contact:{
+      name: "ZITADEL"
+      url: "https://zitadel.com"
+      email: "hi@zitadel.com"
+    }
+    license: {
+      name: "AGPL-3.0-only",
+      url: "https://github.com/zitadel/zitadel/blob/main/LICENSING.md";
+    };
+  };
+  schemes: HTTPS;
+  schemes: HTTP;
+
+  consumes: "application/json";
+  consumes: "application/grpc";
+
+  produces: "application/json";
+  produces: "application/grpc";
+
+  consumes: "application/grpc-web+proto";
+  produces: "application/grpc-web+proto";
+
+  host: "$CUSTOM-DOMAIN";
+  base_path: "/";
+
+  external_docs: {
+    description: "Detailed information about ZITADEL",
+    url: "https://zitadel.com/docs"
+  }
+  security_definitions: {
+    security: {
+      key: "OAuth2";
+      value: {
+        type: TYPE_OAUTH2;
+        flow: FLOW_ACCESS_CODE;
+        authorization_url: "$CUSTOM-DOMAIN/oauth/v2/authorize";
+        token_url: "$CUSTOM-DOMAIN/oauth/v2/token";
+        scopes: {
+          scope: {
+            key: "openid";
+            value: "openid";
+          }
+          scope: {
+            key: "urn:zitadel:iam:org:project:id:zitadel:aud";
+            value: "urn:zitadel:iam:org:project:id:zitadel:aud";
+          }
+        }
+      }
+    }
+  }
+  security: {
+    security_requirement: {
+      key: "OAuth2";
+      value: {
+        scope: "openid";
+        scope: "urn:zitadel:iam:org:project:id:zitadel:aud";
+      }
+    }
+  }
+  responses: {
+    key: "403";
+    value: {
+      description: "Returned when the user does not have permission to access the resource.";
+      schema: {
+        json_schema: {
+          ref: "#/definitions/rpcStatus";
+        }
+      }
+    }
+  }
+  responses: {
+    key: "404";
+    value: {
+      description: "Returned when the resource does not exist.";
+      schema: {
+        json_schema: {
+          ref: "#/definitions/rpcStatus";
+        }
+      }
+    }
+  }
+};
+
+// Service to manage instances and their domains.
+// The service provides methods to create, update, delete and list instances and their domains.
+service InstanceService {
+
+  // Delete Instance
+  //
+  // Deletes an instance with the given ID.
+  //
+  // Required permissions:
+  //   - `system.instance.delete`
+  rpc DeleteInstance(DeleteInstanceRequest) returns (DeleteInstanceResponse) {
+    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
+      responses: {
+        key: "200";
+        value: {
+          description: "The deleted instance.";
+        }
+      };
+    };
+
+    option (google.api.http) = {
+      delete: "/v2beta/instances/{instance_id}"
+    };
+
+    option (zitadel.protoc_gen_zitadel.v2.options) = {
+      auth_option: {
+        permission: "system.instance.delete"
+      }
+    };
+  }
+
+  // Get Instance
+  //
+  // Returns the instance in the current context.
+  //
+  // The instace_id in the input message will be used in the future.
+  //
+  // Required permissions:
+  //   - `iam.read`
+  rpc GetInstance(GetInstanceRequest) returns (GetInstanceResponse) {
+    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
+      responses: {
+        key: "200";
+        value: {
+          description: "The instance of the context.";
+        }
+      };
+    };
+
+    option (google.api.http) = {
+      get: "/v2beta/instances/{instance_id}"
+    };
+
+    option (zitadel.protoc_gen_zitadel.v2.options) = {
+      auth_option: {
+        permission: "iam.read"
+      }
+    };
+  }
+
+  // Update Instance
+  //
+  // Updates instance in context with the given name.
+  //
+  // The instance_id in the input message will be used in the future.
+  //
+  // Required permissions:
+  //   - `iam.write`
+  rpc UpdateInstance(UpdateInstanceRequest) returns (UpdateInstanceResponse) {
+    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
+      responses: {
+        key: "200";
+        value: {
+          description: "The instance was successfully updated.";
+        }
+      };
+    };
+
+    option (google.api.http) = {
+      put: "/v2beta/instances/{instance_id}"
+      body: "*"
+    };
+
+    option (zitadel.protoc_gen_zitadel.v2.options) = {
+      auth_option: {
+        permission: "iam.write"
+      }
+    };
+  }
+
+  // List Instances
+  //
+  // Lists instances matching the given query.
+  // The query can be used to filter either by instance ID or domain.
+  // The request is paginated and returns 100 results by default.
+  //
+  // Required permissions:
+  //  - `system.instance.read`
+  rpc ListInstances(ListInstancesRequest) returns (ListInstancesResponse) {
+    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
+      responses: {
+        key: "200";
+        value: {
+          description: "The list of instances.";
+        }
+      };
+    };
+
+    option (google.api.http) = {
+      post: "/v2beta/instances/search"
+      body: "*"
+    };
+
+    option (zitadel.protoc_gen_zitadel.v2.options) = {
+      auth_option: {
+        permission: "system.instance.read"
+      }
+    };
+  }
+  
+  // Add Custom Domain
+  //
+  // Adds a custom domain to the instance in context.
+  //
+  // The instance_id in the input message will be used in the future
+  //
+  // Required permissions:
+  //   - `system.domain.write`
+  rpc AddCustomDomain(AddCustomDomainRequest) returns (AddCustomDomainResponse) {
+    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
+      responses: {
+        key: "200";
+        value: {
+          description: "The added custom domain.";
+        }
+      };
+    };
+
+    option (google.api.http) = {
+      post: "/v2beta/instances/{instance_id}/custom-domains"
+      body: "*"
+    };
+
+    option (zitadel.protoc_gen_zitadel.v2.options) = {
+      auth_option: {
+        permission: "system.domain.write"
+      }
+    };
+  }
+
+  // Remove Custom Domain
+  //
+  // Removes a custom domain from the instance.
+  //
+  // The instance_id in the input message will be used in the future.
+  //
+  // Required permissions:
+  //  - `system.domain.write`
+  rpc RemoveCustomDomain(RemoveCustomDomainRequest) returns (RemoveCustomDomainResponse) {
+    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
+      responses: {
+        key: "200";
+        value: {
+          description: "The removed custom domain.";
+        }
+      };
+    };
+
+    option (google.api.http) = {
+      delete: "/v2beta/instances/{instance_id}/custom-domains/{domain}"
+    };
+
+    option (zitadel.protoc_gen_zitadel.v2.options) = {
+      auth_option: {
+        permission: "system.domain.write"
+      }
+    };
+  }
+
+  // List Custom Domains
+  //
+  // Lists custom domains of the instance.
+  //
+  // The instance_id in the input message will be used in the future.
+  //
+  // Required permissions:
+  //  - `iam.read`
+  rpc ListCustomDomains(ListCustomDomainsRequest) returns (ListCustomDomainsResponse) {
+    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
+      responses: {
+        key: "200";
+        value: {
+          description: "The list of custom domains.";
+        }
+      };
+    };
+
+    option (google.api.http) = {
+      post: "/v2beta/instances/{instance_id}/custom-domains/search"
+      body: "*"
+    };
+
+    option (zitadel.protoc_gen_zitadel.v2.options) = {
+      auth_option: {
+        permission: "iam.read"
+      }
+    };
+  }
+
+  // Add Trusted Domain
+  //
+  // Adds a trusted domain to the instance.
+  //
+  // The instance_id in the input message will be used in the future.
+  //
+  // Required permissions:
+  //  - `iam.write`
+  rpc AddTrustedDomain(AddTrustedDomainRequest) returns (AddTrustedDomainResponse) {
+    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
+      responses: {
+        key: "200";
+        value: {
+          description: "The added trusted domain.";
+        }
+      };
+    };
+
+    option (google.api.http) = {
+      post: "/v2beta/instances/{instance_id}/trusted-domains"
+      body: "*"
+    };
+
+    option (zitadel.protoc_gen_zitadel.v2.options) = {
+      auth_option: {
+        permission: "iam.write"
+      }
+    };
+  }
+
+  // Remove Trusted Domain
+  //
+  // Removes a trusted domain from the instance.
+  //
+  // The instance_id in the input message will be used in the future.
+  //
+  // Required permissions:
+  //  - `iam.write`
+  rpc RemoveTrustedDomain(RemoveTrustedDomainRequest) returns (RemoveTrustedDomainResponse) {
+    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
+      responses: {
+        key: "200";
+        value: {
+          description: "The removed trusted domain.";
+        }
+      };
+    };
+
+    option (google.api.http) = {
+      delete: "/v2beta/instances/{instance_id}/trusted-domains/{domain}"
+    };
+
+    option (zitadel.protoc_gen_zitadel.v2.options) = {
+      auth_option: {
+        permission: "iam.write"
+      }
+    };
+  }
+
+  
+  // List Trusted Domains
+  //
+  // Lists trusted domains of the instance.
+  //
+  // The instance_id in the input message will be used in the future.
+  //
+  // Required permissions:
+  //   - `iam.read`
+  rpc ListTrustedDomains(ListTrustedDomainsRequest) returns (ListTrustedDomainsResponse) {
+    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
+      responses: {
+        key: "200";
+        value: {
+          description: "The list of trusted domains.";
+        }
+      };
+    };
+
+    option (google.api.http) = {
+      post: "/v2beta/instances/{instance_id}/trusted-domains/search"
+      body: "*"
+    };
+
+    option (zitadel.protoc_gen_zitadel.v2.options) = {
+      auth_option: {
+        permission: "iam.read"
+      }
+    };
+  }
+}
+
+message DeleteInstanceRequest {
+  string instance_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: "\"222430354126975533\"";
+    }
+  ];
+}
+
+message DeleteInstanceResponse {
+  google.protobuf.Timestamp deletion_date = 1 [
+    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+      example: "\"2025-01-23T10:34:18.051Z\"";
+    }
+  ];
+}
+
+message GetInstanceRequest {
+  string instance_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: "\"222430354126975533\"";
+    }
+  ];
+}
+
+message GetInstanceResponse {
+  zitadel.instance.v2beta.Instance instance = 1;
+}
+
+message UpdateInstanceRequest {
+  // used only to identify the instance to change.
+  string instance_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: "\"222430354126975533\"";
+    }
+  ];
+  string instance_name = 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: "\"name of the instance to update\"";
+      example: "\"my instance\"";
+    }
+  ];
+}
+
+message UpdateInstanceResponse {
+  google.protobuf.Timestamp change_date = 1 [
+    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+      example: "\"2025-01-23T10:34:18.051Z\"";
+    }
+  ];
+}
+
+message ListInstancesRequest {
+  // Criterias the client is looking for.
+  repeated Query queries = 1;
+
+  // Pagination and sorting.
+  zitadel.filter.v2beta.PaginationRequest pagination = 2;
+  
+  // The field the result is sorted by.
+  optional FieldName sorting_column = 3;
+}
+
+message ListInstancesResponse {
+  // The list of instances.
+  repeated Instance instances = 1;
+
+  // Contains the total number of instances matching the query and the applied limit.
+  zitadel.filter.v2beta.PaginationResponse pagination = 2;
+}
+
+message AddCustomDomainRequest {
+  string instance_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: "\"222430354126975533\"";
+    }
+  ];
+  string domain = 2 [
+    (validate.rules).string = {min_len: 1, max_len: 253},
+    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+      min_length: 1;
+      max_length: 253;
+    }
+  ];
+}
+
+message AddCustomDomainResponse {
+  google.protobuf.Timestamp creation_date = 1 [
+    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+      example: "\"2025-01-23T10:34:18.051Z\"";
+    }
+  ];
+}
+
+message RemoveCustomDomainRequest {
+  string instance_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: "\"222430354126975533\"";
+    }
+  ];
+  string domain = 2 [
+    (validate.rules).string = {min_len: 1, max_len: 253},
+    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+      min_length: 1;
+      max_length: 253;
+    }
+  ];
+}
+
+message RemoveCustomDomainResponse {
+  google.protobuf.Timestamp deletion_date = 1 [
+    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+      example: "\"2025-01-23T10:34:18.051Z\"";
+    }
+  ];
+}
+
+message ListCustomDomainsRequest {
+  string instance_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: "\"222430354126975533\"";
+    }
+  ];
+
+  // Pagination and sorting.
+  zitadel.filter.v2beta.PaginationRequest pagination = 2;
+
+  // The field the result is sorted by.
+  DomainFieldName sorting_column = 3;
+
+  // Criterias the client is looking for.
+  repeated DomainSearchQuery queries = 4;
+}
+
+message ListCustomDomainsResponse {
+  repeated Domain domains = 1;
+
+  // Contains the total number of domains matching the query and the applied limit.
+  zitadel.filter.v2beta.PaginationResponse pagination = 2;
+}
+
+message AddTrustedDomainRequest {
+  string instance_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: "\"222430354126975533\"";
+    }
+  ];
+  string domain = 2 [
+    (validate.rules).string = {min_len: 1, max_len: 253},
+    (google.api.field_behavior) = REQUIRED,
+    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+        example: "\"login.example.com\"";
+        min_length: 1;
+        max_length: 253;
+    }
+  ];
+}
+
+message AddTrustedDomainResponse {
+  google.protobuf.Timestamp creation_date = 1 [
+    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+      example: "\"2025-01-23T10:34:18.051Z\"";
+    }
+  ];
+}
+
+message RemoveTrustedDomainRequest {
+  string instance_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: "\"222430354126975533\"";
+    }
+  ];
+  string domain = 2 [
+    (validate.rules).string = {min_len: 1, max_len: 253},
+    (google.api.field_behavior) = REQUIRED,
+    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+        example: "\"login.example.com\"";
+        min_length: 1;
+        max_length: 253;
+    }
+  ];
+}
+
+message RemoveTrustedDomainResponse {
+  google.protobuf.Timestamp deletion_date = 1 [
+    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
+      example: "\"2025-01-23T10:34:18.051Z\"";
+    }
+  ];
+}
+
+message ListTrustedDomainsRequest {
+  string instance_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: "\"222430354126975533\"";
+    }
+  ];
+
+  // Pagination and sorting.
+  zitadel.filter.v2beta.PaginationRequest pagination = 2;
+
+  // The field the result is sorted by.
+  TrustedDomainFieldName sorting_column = 3;
+  
+  // Criterias the client is looking for.
+  repeated TrustedDomainSearchQuery queries = 4;
+}
+
+message ListTrustedDomainsResponse {
+  repeated TrustedDomain trusted_domain = 1;
+
+  // Contains the total number of domains matching the query and the applied limit.
+  zitadel.filter.v2beta.PaginationResponse pagination = 2;
+}

proto/zitadel/system.proto

@@ -117,6 +117,8 @@ service SystemService {
   }
 
   // Returns a list of ZITADEL instances
+  //
+  // Deprecated: Use [ListInstances](apis/resources/instance_service_v2/instance-service-list-instances.api.mdx) instead to list instances
   rpc ListInstances(ListInstancesRequest) returns (ListInstancesResponse) {
     option (google.api.http) = {
       post: "/instances/_search"
@@ -126,9 +128,15 @@ service SystemService {
     option (zitadel.v1.auth_option) = {
       permission: "system.instance.read";
     };
+
+    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
+        deprecated: true;
+    };
   }
 
   // Returns the detail of an instance
+  //
+  // Deprecated: Use [GetInstance](apis/resources/instance_service_v2/instance-service-get-instance.api.mdx) instead to get the details of the instance in context
   rpc GetInstance(GetInstanceRequest) returns (GetInstanceResponse) {
     option (google.api.http) = {
       get: "/instances/{instance_id}";
@@ -137,6 +145,10 @@ service SystemService {
     option (zitadel.v1.auth_option) = {
       permission: "system.instance.read";
     };
+
+    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
+        deprecated: true;
+    };
   }
 
   // Deprecated: Use CreateInstance instead
@@ -151,9 +163,15 @@ service SystemService {
     option (zitadel.v1.auth_option) = {
       permission: "system.instance.write";
     };
+
+    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
+        deprecated: true;
+    };
   }
 
   // Updates name of an existing instance
+  //
+  // Deprecated: Use [UpdateInstance](apis/resources/instance_service_v2/instance-service-update-instance.api.mdx) instead to update the name of the instance in context
   rpc UpdateInstance(UpdateInstanceRequest) returns (UpdateInstanceResponse) {
     option (google.api.http) = {
       put: "/instances/{instance_id}"
@@ -163,6 +181,10 @@ service SystemService {
     option (zitadel.v1.auth_option) = {
       permission: "system.instance.write";
     };
+
+    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
+        deprecated: true;
+    };
   }
 
   // Creates a new instance with all needed setup data
@@ -180,6 +202,8 @@ service SystemService {
 
   // Removes an instance
   // This might take some time
+  //
+  // Deprecated: Use [DeleteInstance](apis/resources/instance_service_v2/instance-service-delete-instance.api.mdx) instead to delete an instance
   rpc RemoveInstance(RemoveInstanceRequest) returns (RemoveInstanceResponse) {
     option (google.api.http) = {
       delete: "/instances/{instance_id}"
@@ -188,6 +212,10 @@ service SystemService {
     option (zitadel.v1.auth_option) = {
       permission: "system.instance.delete";
     };
+
+    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
+        deprecated: true;
+    };
   }
 
   //Returns all instance members matching the request
@@ -204,7 +232,9 @@ service SystemService {
     };
   }
 
-  //Checks if a domain exists
+  // Checks if a domain exists
+  //
+  // Deprecated: Use [ListCustomDomains](apis/resources/instance_service_v2/instance-service-list-custom-domains.api.mdx) instead to check existence of an instance
   rpc ExistsDomain(ExistsDomainRequest) returns (ExistsDomainResponse) {
     option (google.api.http) = {
       post: "/domains/{domain}/_exists";
@@ -214,10 +244,14 @@ service SystemService {
     option (zitadel.v1.auth_option) = {
       permission: "system.domain.read";
     };
+
+    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
+        deprecated: true;
+    };
   }
 
   // Returns the custom domains of an instance
-  //Checks if a domain exists
+  // Checks if a domain exists
   // Deprecated: Use the Admin APIs ListInstanceDomains on the admin API instead
   rpc ListDomains(ListDomainsRequest) returns (ListDomainsResponse) {
     option (google.api.http) = {
@@ -228,9 +262,15 @@ service SystemService {
     option (zitadel.v1.auth_option) = {
       permission: "system.domain.read";
     };
+
+    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
+        deprecated: true;
+    };
   }
 
   // Adds a domain to an instance
+  //
+  // Deprecated: Use [AddCustomDomain](apis/resources/instance_service_v2/instance-service-add-custom-domain.api.mdx) instead to add a custom domain to the instance in context
   rpc AddDomain(AddDomainRequest) returns (AddDomainResponse) {
     option (google.api.http) = {
       post: "/instances/{instance_id}/domains";
@@ -240,9 +280,15 @@ service SystemService {
     option (zitadel.v1.auth_option) = {
       permission: "system.domain.write";
     };
+
+    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
+        deprecated: true;
+    };
   }
 
   // Removes the domain of an instance
+  //
+  // Deprecated: Use [RemoveDomain](apis/resources/instance_service_v2/instance-service-remove-custom-domain.api.mdx) instead to remove a custom domain from the instance in context
   rpc RemoveDomain(RemoveDomainRequest) returns (RemoveDomainResponse) {
     option (google.api.http) = {
       delete: "/instances/{instance_id}/domains/{domain}";
@@ -251,6 +297,10 @@ service SystemService {
     option (zitadel.v1.auth_option) = {
       permission: "system.domain.delete";
     };
+
+    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
+        deprecated: true;
+    };
   }
 
   // Sets the primary domain of an instance