zitadel/proto/zitadel/system.proto

syntax = "proto3";

import "zitadel/object.proto";
import "zitadel/options.proto";
import "zitadel/instance.proto";

import "google/api/annotations.proto";
import "google/protobuf/timestamp.proto";
import "protoc-gen-openapiv2/options/annotations.proto";
import "validate/validate.proto";

package zitadel.system.v1;

option go_package = "github.com/zitadel/zitadel/pkg/grpc/system";

option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_swagger) = {
  info: {
    title: "System API";
    version: "1.0";
    description: "This API is intended to configure and manage the different tenants whithin ZITADEL.";
    contact:{
      name: "ZITADEL"
      url: "https://zitadel.com"
      email: "hi@zitadel.com"
    }
    license: {
      name: "Apache 2.0",
      url: "https://github.com/zitadel/zitadel/blob/main/LICENSE";
    };
  };

  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: "api.zitadel.ch";
  base_path: "/system/v1";

  external_docs: {
    description: "Detailed information about ZITADEL",
    url: "https://docs.zitadel.com"
  }

  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 SystemService {
  //Indicates if ZITADEL is running.
  // It respondes as soon as ZITADEL started
  rpc Healthz(HealthzRequest) returns (HealthzResponse) {
    option (google.api.http) = {
      get: "/healthz";
    };

    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
      tags: "probes";
      responses: {
        key: "200";
        value: {
          description: "ZITADEL started";
        };
      }
      responses: {
        key: "default";
        value: {
          description: "ZITADEL NOT started yet";
        };
      }
    };
  }

  // Returns a list of ZITADEL instances
  rpc ListInstances(ListInstancesRequest) returns (ListInstancesResponse) {
    option (google.api.http) = {
      post: "/instances/_search"
      body: "*"
    };

    option (zitadel.v1.auth_option) = {
      permission: "authenticated";
    };
  }

  // Returns the detail of an instance
  rpc GetInstance(GetInstanceRequest) returns (GetInstanceResponse) {
    option (google.api.http) = {
      get: "/instances/{instance_id}";
    };

    option (zitadel.v1.auth_option) = {
      permission: "authenticated";
    };
  }

  // Creates a new instance with all needed setup data
  // This might take some time
  rpc AddInstance(AddInstanceRequest) returns (AddInstanceResponse) {
    option (google.api.http) = {
      post: "/instances"
      body: "*"
    };

    option (zitadel.v1.auth_option) = {
      permission: "authenticated";
    };
  }

  // Removes a instances
  // This might take some time
  rpc RemoveInstance(RemoveInstanceRequest) returns (RemoveInstanceResponse) {
    option (google.api.http) = {
      delete: "/instances/{instance_id}"
    };

    option (zitadel.v1.auth_option) = {
      permission: "authenticated";
    };
  }

  // Checks if a domain exists
  rpc ExistsDomain(ExistsDomainRequest) returns (ExistsDomainResponse) {
    option (google.api.http) = {
      post: "/domains/{domain}/_exists";
      body: "*"
    };

    option (zitadel.v1.auth_option) = {
      permission: "authenticated";
    };
  }

  // Returns the custom domains of an instance
  rpc ListDomains(ListDomainsRequest) returns (ListDomainsResponse) {
    option (google.api.http) = {
      post: "/instances/{instance_id}/domains/_search";
      body: "*"
    };

    option (zitadel.v1.auth_option) = {
      permission: "authenticated";
    };
  }

  // Returns the domain of an instance
  rpc AddDomain(AddDomainRequest) returns (AddDomainResponse) {
    option (google.api.http) = {
      post: "/instances/{instance_id}/domains";
      body: "*"
    };

    option (zitadel.v1.auth_option) = {
      permission: "authenticated";
    };
  }

  // Returns the domain of an instance
  rpc RemoveDomain(RemoveDomainRequest) returns (RemoveDomainResponse) {
    option (google.api.http) = {
      delete: "/instances/{instance_id}/domains/{domain}";
    };

    option (zitadel.v1.auth_option) = {
      permission: "authenticated";
    };
  }

  // Returns the domain of an instance
  rpc SetPrimaryDomain(SetPrimaryDomainRequest) returns (SetPrimaryDomainResponse) {
    option (google.api.http) = {
      post: "/instances/{instance_id}/domains/_set_primary";
      body: "*"
    };

    option (zitadel.v1.auth_option) = {
      permission: "authenticated";
    };
  }

  //Returns all stored read models of ZITADEL
  // views are used for search optimisation and optimise request latencies
  // they represent the delta of the event happend on the objects
  rpc ListViews(ListViewsRequest) returns (ListViewsResponse) {
    option (google.api.http) = {
      post: "/views/_search";
      body: "*"
    };

    option (zitadel.v1.auth_option) = {
      permission: "authenticated";
    };

    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
      tags: "views";
      external_docs: {
        url: "https://docs.zitadel.com/concepts#Software_Architecture";
        description: "details of ZITADEL's event driven software concepts";
      };
      responses: {
        key: "200";
        value: {
          description: "Views for query operations";
        };
      };
    };
  }

  //Truncates the delta of the change stream
  // be carefull with this function because ZITADEL has to
  // recompute the deltas after they got cleared.
  // Search requests will return wrong results until all deltas are recomputed
  rpc ClearView(ClearViewRequest) returns (ClearViewResponse) {
    option (google.api.http) = {
      post: "/views/{database}/{view_name}";
    };

    option (zitadel.v1.auth_option) = {
      permission: "authenticated";
    };

    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
      tags: "views";
      external_docs: {
        url: "https://docs.zitadel.com/concepts#Software_Architecture";
        description: "details of ZITADEL's event driven software concepts";
      };
      responses: {
        key: "200";
        value: {
          description: "View cleared";
        };
      };
    };
  }

  //Returns event descriptions which cannot be processed.
  // It's possible that some events need some retries.
  // For example if the SMTP-API wasn't able to send an email at the first time
  rpc ListFailedEvents(ListFailedEventsRequest) returns (ListFailedEventsResponse) {
    option (google.api.http) = {
      post: "/failedevents/_search";
      body: "*"
    };

    option (zitadel.v1.auth_option) = {
      permission: "authenticated";
    };

    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
      tags: "failed events";
      external_docs: {
        url: "https://docs.zitadel.com/concepts#Software_Architecture";
        description: "details of ZITADEL's event driven software concepts";
      };
      responses: {
        key: "200";
        value: {
          description: "Events which were not processed by the views";
        };
      };
    };
  }

  //Deletes the event from failed events view.
  // the event is not removed from the change stream
  // This call is usefull if the system was able to process the event later.
  // e.g. if the second try of sending an email was successful. the first try produced a
  // failed event. You can find out if it worked on the `failure_count`
  rpc RemoveFailedEvent(RemoveFailedEventRequest) returns (RemoveFailedEventResponse) {
    option (google.api.http) = {
      delete: "/failedevents/{database}/{view_name}/{failed_sequence}";
    };

    option (zitadel.v1.auth_option) = {
      permission: "authenticated";
    };

    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
      tags: "failed events";
      external_docs: {
        url: "https://docs.zitadel.com/concepts#Software_Architecture";
        description: "details of ZITADEL's event driven software concepts";
      };
      responses: {
        key: "200";
        value: {
          description: "Events removed from the list";
        };
      };
      responses: {
        key: "400";
        value: {
          description: "failed event not found";
          schema: {
            json_schema: {
              ref: "#/definitions/rpcStatus";
            };
          };
        };
      };
    };
  }
}


//This is an empty request
message HealthzRequest {}

//This is an empty response
message HealthzResponse {}

message ListInstancesRequest {
  option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_schema) = {
    json_schema: {
      description: "Search query for lists";
      required: ["query"]
    };
  };

  //list limitations and ordering
  zitadel.v1.ListQuery query = 1;
  // the field the result is sorted
  zitadel.instance.v1.FieldName sorting_column = 2;
  //criterias the client is looking for
  repeated zitadel.instance.v1.Query queries = 3;
}

message ListInstancesResponse {
  zitadel.v1.ListDetails details = 1;
  zitadel.instance.v1.FieldName sorting_column = 2;
  repeated zitadel.instance.v1.Instance result = 3;
}

message GetInstanceRequest {
  string instance_id = 1 [(validate.rules).string = {min_len: 1, max_len: 200}];
}

message GetInstanceResponse {
  zitadel.instance.v1.InstanceDetail instance = 1;
}

message AddInstanceRequest {
  message Profile {
    string first_name = 1 [(validate.rules).string = {max_len: 200}];
    string last_name = 2 [(validate.rules).string = {max_len: 200}];
    string preferred_language = 5 [(validate.rules).string = {max_len: 10}];
  }
  message Email {
    string email = 1[(validate.rules).string = {min_len: 1, max_len: 200}];
    bool is_email_verified = 2;
  }
  message Password {
    string password = 1 [(validate.rules).string = {max_len: 200}];
    bool password_change_required = 2;
  }

  string instance_name = 1 [(validate.rules).string = {min_len: 1, max_len: 200}];
  string first_org_name = 2 [(validate.rules).string = {max_len: 200}];
  string custom_domain = 3 [(validate.rules).string = {max_len: 200}];
  string owner_user_name = 4 [(validate.rules).string = {max_len: 200}];
  Email owner_email = 5 [(validate.rules).message.required = true];
  Profile owner_profile = 6 [(validate.rules).message.required = false];
  Password owner_password = 7 [(validate.rules).message.required = false];
  string default_language = 8 [(validate.rules).string = {max_len: 10}];
}

message AddInstanceResponse {
  string instance_id = 1;
  zitadel.v1.ObjectDetails details = 2;
}

message RemoveInstanceRequest {
  string instance_id = 1 [(validate.rules).string = {min_len: 1, max_len: 200}];
}

message RemoveInstanceResponse {
  zitadel.v1.ObjectDetails details = 1;
}

message GetUsageRequest {
  string instance_id = 1 [(validate.rules).string = {min_len: 1, max_len: 200}];
}

message GetUsageResponse {
  zitadel.v1.ObjectDetails details = 1;
  uint64 executed_requests = 2;
  uint64 executed_action_mins = 3;
}

message ExistsDomainRequest {
  string domain = 1 [(validate.rules).string = {min_len: 1, max_len: 200}];
}

message ExistsDomainResponse {
  bool exists = 1;
}

message ListDomainsRequest {
  string instance_id = 1 [(validate.rules).string = {min_len: 1, max_len: 200}];//list limitations and ordering
  zitadel.v1.ListQuery query = 2;
  // the field the result is sorted
  zitadel.instance.v1.DomainFieldName sorting_column = 3;
  //criterias the client is looking for
  repeated zitadel.instance.v1.DomainSearchQuery queries = 4;
}

message ListDomainsResponse {
  zitadel.v1.ListDetails details = 1;
  zitadel.instance.v1.DomainFieldName sorting_column = 2;
  repeated zitadel.instance.v1.Domain result = 3;
}

message AddDomainRequest {
  string instance_id = 1 [(validate.rules).string = {min_len: 1, max_len: 200}];
  string domain = 2 [(validate.rules).string = {min_len: 1, max_len: 200}];
}

message AddDomainResponse {
  zitadel.v1.ObjectDetails details = 1;
}

message RemoveDomainRequest {
  string instance_id = 1 [(validate.rules).string = {min_len: 1, max_len: 200}];
  string domain = 2 [(validate.rules).string = {min_len: 1, max_len: 200}];
}

message RemoveDomainResponse {
  zitadel.v1.ObjectDetails details = 1;
}

message SetPrimaryDomainRequest {
  string instance_id = 1 [(validate.rules).string = {min_len: 1, max_len: 200}];
  string domain = 2 [(validate.rules).string = {min_len: 1, max_len: 200}];
}

message SetPrimaryDomainResponse {
  zitadel.v1.ObjectDetails details = 1;
}

message ChangeSubscriptionRequest {
  string domain = 1 [(validate.rules).string = {min_len: 1, max_len: 200}];
  string subscription_name = 2 [(validate.rules).string = {min_len: 1, max_len: 200}];
  uint64 request_limit = 3;
  uint64 action_mins_limit = 4;
}

message ChangeSubscriptionResponse {
  zitadel.v1.ObjectDetails details = 1;
}

//This is an empty request
message ListViewsRequest {}

message ListViewsResponse {
  //TODO: list details
  repeated View result = 1;
}

message ClearViewRequest {
  option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_schema) = {
    json_schema: {
      required: ["database", "view_name"]
    };
  };

  string database = 1 [
    (validate.rules).string = {min_len: 1, max_len: 200},
    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
      example: "\"adminapi\"";
      min_length: 1;
      max_length: 200;
    }
  ];
  string view_name = 2 [
    (validate.rules).string = {min_len: 1, max_len: 200},
    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
      example: "\"iam_members\"";
      min_length: 1;
      max_length: 200;
    }
  ];
}

//This is an empty response
message ClearViewResponse {}

//This is an empty request
message ListFailedEventsRequest {}

message ListFailedEventsResponse {
  //TODO: list details
  repeated FailedEvent result = 1;
}

message RemoveFailedEventRequest {
  option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_schema) = {
    json_schema: {
      required: ["database", "view_name", "failed_sequence"]
    };
  };

  string database = 1 [
    (validate.rules).string = {min_len: 1, max_len: 200},
    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
      example: "\"adminapi\"";
      min_length: 1;
      max_length: 200;
    }
  ];
  string view_name = 2 [
    (validate.rules).string = {min_len: 1, max_len: 200},
    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
      example: "\"iam_members\"";
      min_length: 1;
      max_length: 200;
    }
  ];
  uint64 failed_sequence = 3 [
    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
      example: "\"9823758\"";
    }
  ];
}

//This is an empty response
message RemoveFailedEventResponse {}

message View {
  string database = 1 [
    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
      example: "\"adminapi\"";
    }
  ];
  string view_name = 2 [
    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
      example: "\"iam_members\"";
    }
  ];
  uint64 processed_sequence = 3 [
    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
      example: "\"9823758\"";
    }
  ];
  google.protobuf.Timestamp event_timestamp = 4 [
    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
      example: "\"2019-04-01T08:45:00.000000Z\"";
      description: "The timestamp the event occured";
    }
  ]; // The timestamp the event occured
  google.protobuf.Timestamp last_successful_spooler_run = 5 [
    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
      description: "The timestamp the event occured";
    }
  ];
  string instance = 6  [
    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
      example: "\"840498034930840\"";
    }
  ];
}

message FailedEvent {
  string database = 1 [
    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
      example: "\"adminapi\"";
    }
  ];
  string view_name = 2 [
    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
      example: "\"iam_members\"";
    }
  ];
  uint64 failed_sequence = 3 [
    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
      example: "\"9823759\"";
    }
  ];
  uint64 failure_count = 4 [
    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
      example: "\"5\"";
    }
  ];
  string error_message = 5 [
    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
      example: "\"ID=EXAMP-ID3ER Message=Example message\"";
    }
  ];
}