zitadel/proto/zitadel/system.proto

syntax = "proto3";

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

import "google/api/annotations.proto";
import "google/protobuf/timestamp.proto";
import "google/protobuf/duration.proto";

import "protoc-gen-openapiv2/options/annotations.proto";

import "validate/validate.proto";

package zitadel.system.v1;

option go_package ="github.com/caos/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: "CAOS developers of ZITADEL"
            url: "https://zitadel.ch"
            email: "[email protected]"
        }
        license: {
            name: "Apache 2.0",
            url: "https://github.com/caos/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.ch"
    }

    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/tenants
    rpc ListInstances(ListInstancesRequest) returns (ListInstancesResponse) {
        option (google.api.http) = {
            post: "/instances"
            body: "*"
        };
    }

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

    // 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: "*"
        };
    }

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

    // Returns the usage metrics of an instance
    rpc GetUsage(GetUsageRequest) returns (GetUsageResponse) {
        option (google.api.http) = {
            get: "/instances/{id}/usage";
        };
    }

    // Returns the domain of an instance
    rpc GetGeneratedDomain(GetGeneratedDomainRequest) returns (GetGeneratedDomainResponse) {
        option (google.api.http) = {
            get: "/instances/{id}/domains/generated";
        };
    }

    // Returns the custom domains of an instance
    rpc GetCustomDomains(GetCustomDomainsRequest) returns (GetCustomDomainsResponse) {
        option (google.api.http) = {
            get: "/instances/{id}/domains/custom";
        };
    }

    // Returns the domain of an instance
    rpc AddCustomDomain(AddCustomDomainRequest) returns (AddCustomDomainResponse) {
        option (google.api.http) = {
            post: "/instances/{id}/domains/custom";
            body: "*"
        };
    }

    //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";
        };

        option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
            tags: "views";
            external_docs: {
                url: "https://docs.zitadel.ch/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: "iam.write";
        };

        option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
            tags: "views";
            external_docs: {
                url: "https://docs.zitadel.ch/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";
        };

        option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
            tags: "failed events";
            external_docs: {
                url: "https://docs.zitadel.ch/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 (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
            tags: "failed events";
            external_docs: {
                url: "https://docs.zitadel.ch/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 id = 1 [(validate.rules).string = {min_len: 1, max_len: 200}];
}

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

message AddInstanceRequest {
    string instance_name = 1 [(validate.rules).string = {min_len: 1, max_len: 200}];
    string first_org_name = 2 [(validate.rules).string = {min_len: 1, max_len: 200}];
    string custom_domain = 3 [(validate.rules).string = {max_len: 200}];
    string owner_first_name = 4 [(validate.rules).string = {min_len: 1, max_len: 200}];
    string owner_last_name = 5 [(validate.rules).string = {min_len: 1, max_len: 200}];
    string owner_email = 6 [(validate.rules).string = {min_len: 1, max_len: 200}];
    string owner_username = 7 [(validate.rules).string = {min_len: 1, max_len: 200}];
    string password = 8 [(validate.rules).string = {min_len: 1, max_len: 200}];
    uint64 request_limit = 9;
    uint64 action_mins_limit = 10;
}

message AddInstanceResponse {
    string id = 1;
}

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

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

message GetUsageRequest {
    string 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 GetGeneratedDomainRequest {
    string id = 1 [(validate.rules).string = {min_len: 1, max_len: 200}];
}

message GetGeneratedDomainResponse {
    zitadel.v1.ObjectDetails details = 1;
    string domain = 2;
}

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

message GetCustomDomainsResponse {
    zitadel.v1.ObjectDetails details = 1;
    repeated string domains = 2;
}

message AddCustomDomainRequest {
    string id = 1 [(validate.rules).string = {min_len: 1, max_len: 200}];
    string custom_domain = 2 [(validate.rules).string = {min_len: 1, max_len: 200}];
}

message AddCustomDomainResponse {
    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\"";
        }
    ];
}