zitadel/pkg/auth/api/proto/auth.proto

syntax = "proto3";

import "google/api/annotations.proto";
import "google/protobuf/empty.proto";
import "google/protobuf/struct.proto";
import "google/protobuf/timestamp.proto";
import "validate/validate.proto";
import "protoc-gen-swagger/options/annotations.proto";
import "authoption/options.proto";

package zitadel.auth.api.v1;

option go_package = "github.com/caos/zitadel/pkg/auth/api/grpc";

option (grpc.gateway.protoc_gen_swagger.options.openapiv2_swagger) = {
    info: {
        title: "Auth API";
        version: "0.1";
        contact:{
            url: "https://github.com/caos/zitadel/pkg/auth"
        };
    };

    schemes: HTTPS;

    consumes: "application/json";
    consumes: "application/grpc";

    produces: "application/json";
    produces: "application/grpc";
};

service AuthService {
    // Readiness
    rpc Healthz(google.protobuf.Empty) returns (google.protobuf.Empty) {
        option (google.api.http) = {
            get: "/healthz"
            };
    }

    rpc Ready(google.protobuf.Empty) returns (google.protobuf.Empty) {
        option (google.api.http) = {
            get: "/ready"
            };
    }

    rpc Validate(google.protobuf.Empty) returns (google.protobuf.Struct) {
        option (google.api.http) = {
            get: "/validate"
            };
    }

    // Authorization
    rpc GetMyUserSessions(google.protobuf.Empty) returns (UserSessionViews) {
        option (google.api.http) = {
                get: "/me/usersessions"
            };

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

    //User
    rpc GetMyUserProfile(google.protobuf.Empty) returns (UserProfile) {
        option (google.api.http) = {
                get: "/users/me/profile"
            };

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

    rpc UpdateMyUserProfile(UpdateUserProfileRequest) returns (UserProfile) {
        option (google.api.http) = {
                put: "/users/me/profile"
                body: "*"
            };

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

    rpc GetMyUserEmail(google.protobuf.Empty) returns (UserEmail) {
        option (google.api.http) = {
                get: "/users/me/email"
            };

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

    rpc ChangeMyUserEmail(UpdateUserEmailRequest) returns (UserEmail) {
        option (google.api.http) = {
                put: "/users/me/email"
                body: "*"
            };

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

    rpc VerifyMyUserEmail(VerifyMyUserEmailRequest) returns (google.protobuf.Empty) {
        option (google.api.http) = {
                post: "/users/me/email/_verify"
                body: "*"
            };

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

    rpc ResendMyEmailVerificationMail(google.protobuf.Empty) returns (google.protobuf.Empty) {
        option (google.api.http) = {
                post: "/users/me/email/_resendverification"
                body: "*"
            };

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

    rpc GetMyUserPhone(google.protobuf.Empty) returns (UserPhone) {
        option (google.api.http) = {
                get: "/users/me/phone"
            };

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

    rpc ChangeMyUserPhone(UpdateUserPhoneRequest) returns (UserPhone) {
        option (google.api.http) = {
                put: "/users/me/phone"
                body: "*"
            };

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

    rpc VerifyMyUserPhone(VerifyUserPhoneRequest) returns (google.protobuf.Empty) {
        option (google.api.http) = {
                post: "/users/me/phone/_verify"
                body: "*"
            };

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

    rpc ResendMyPhoneVerificationCode(google.protobuf.Empty) returns (google.protobuf.Empty) {
        option (google.api.http) = {
                post: "/users/me/phone/_resendverification"
                body: "*"
            };

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

    rpc GetMyUserAddress(google.protobuf.Empty) returns (UserAddress) {
        option (google.api.http) = {
                get: "/users/me/address"
            };

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

    rpc UpdateMyUserAddress(UpdateUserAddressRequest) returns (UserAddress) {
        option (google.api.http) = {
                put: "/users/me/address"
                body: "*"
            };

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

    rpc GetMyMfas(google.protobuf.Empty) returns (MultiFactors) {
        option (google.api.http) = {
                get: "/users/me/mfas"
            };

        option (caos.zitadel.utils.v1.auth_option) = {
                permission: "authenticated"
            };
    }
    //Password

    rpc SetMyPassword(PasswordRequest) returns (google.protobuf.Empty) {
        option (google.api.http) = {
                put: "/users/me/passwords"
                body: "*"
            };

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

    rpc ChangeMyPassword(PasswordChange) returns (google.protobuf.Empty) {
        option (google.api.http) = {
                put: "/users/me/passwords/_change"
                body: "*"
            };

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

    // MFA
    rpc AddMfaOTP(google.protobuf.Empty) returns (MfaOtpResponse) {
        option (google.api.http) = {
                post: "/users/me/mfa/otp"
                body: "*"
            };
        option (caos.zitadel.utils.v1.auth_option) = {
                permission: "authenticated"
            };
    }

    rpc VerifyMfaOTP(VerifyMfaOtp) returns (MfaOtpResponse) {
        option (google.api.http) = {
                put: "/users/me/mfa/otp/_verify"
                body: "*"
            };

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

    rpc RemoveMfaOTP(google.protobuf.Empty) returns (google.protobuf.Empty) {
        option (google.api.http) = {
                delete: "/users/me/mfa/otp"
            };

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

    rpc SearchMyProjectOrgs(MyProjectOrgSearchRequest) returns (MyProjectOrgSearchResponse) {
        option (google.api.http) = {
                post: "/global/projectorgs/_search"
                body: "*"
            };

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

    rpc IsIamAdmin(google.protobuf.Empty) returns (IsAdminResponse) {
        option (google.api.http) = {
                get: "/global/_isiamadmin"
            };

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

    //Permission
    rpc GetMyZitadelPermissions(google.protobuf.Empty) returns (MyPermissions) {
        option (google.api.http) = {
                get: "/permissions/zitadel/me"
            };

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

message UserSessionViews {
    repeated UserSessionView user_sessions = 1;
}
message UserSessionView {
    string id = 1;
    string agent_id = 2;
    UserSessionState auth_state = 3;
    string user_id = 4;
    string user_name = 5;
    uint64 sequence = 6;
}

enum UserSessionState {
    USERSESSIONSTATE_UNSPECIFIED = 0;
    USERSESSIONSTATE_ACTIVE = 1;
    USERSESSIONSTATE_TERMINATED = 2;
}

enum OIDCResponseType {
    OIDCRESPONSETYPE_CODE = 0;
    OIDCRESPONSETYPE_ID_TOKEN = 1;
    OIDCRESPONSETYPE_ID_TOKEN_TOKEN = 2;
}

message User {
    string id = 1;
    UserState state = 2;
    google.protobuf.Timestamp creation_date = 3;
    google.protobuf.Timestamp activation_date = 4;
    google.protobuf.Timestamp change_date = 5;
    google.protobuf.Timestamp last_login = 6;
    google.protobuf.Timestamp password_changed = 7;
    string user_name = 8;
    string first_name = 9;
    string last_name = 10;
    string nick_name = 11;
    string display_name = 12;
    string preferred_language = 13;
    Gender gender = 14;
    string email = 15;
    bool is_email_verified = 16;
    string phone = 17;
    bool is_phone_verified = 18;
    string country = 19;
    string locality = 20;
    string postal_code = 21;
    string region = 22;
    string street_address = 23;
    bool password_change_required = 24;
    uint64 sequence = 25;
}

enum UserState {
    USERSTATE_UNSPECIEFIED = 0;
    USERSTATE_ACTIVE = 1;
    USERSTATE_INACTIVE = 2;
    USERSTATE_DELETED = 3;
    USERSTATE_LOCKED = 4;
    USERSTATE_SUSPEND = 5;
    USERSTATE_INITIAL= 6;
}

enum Gender {
    GENDER_UNSPECIFIED = 0;
    GENDER_FEMALE = 1;
    GENDER_MALE = 2;
    GENDER_DIVERSE = 3;
}

message UserProfile {
    string id = 1;
    string user_name = 2;
    string first_name = 3;
    string last_name = 4;
    string nick_name = 5;
    string display_name = 6;
    string preferred_language = 7;
    Gender gender = 8;
    uint64 sequence = 26;
}

message UpdateUserProfileRequest {
    string first_name = 1 [(validate.rules).string = {min_len: 1, max_len: 200}];
    string last_name = 2 [(validate.rules).string = {min_len: 1, max_len: 200}];
    string nick_name = 3 [(validate.rules).string = {min_len: 1, max_len: 200}];
    string display_name = 4 [(validate.rules).string = {min_len: 1, max_len: 200}];
    string preferred_language = 5 [(validate.rules).string = {min_len: 1, max_len: 200}];
    Gender gender = 6;
}

message UserEmail {
    string id = 1;
    string email = 2;
    bool isEmailVerified = 3;
    uint64 sequence = 4;
}

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

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

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

message UserPhone {
    string id = 1;
    string phone = 2;
    bool is_phone_verified = 3;
    uint64 sequence = 4;
}

message UpdateUserPhoneRequest {
    string phone = 1 [(validate.rules).string = {min_len: 1, max_len: 20}];
}

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

message UserAddress {
    string id = 1;
    string country = 2;
    string locality = 3;
    string postal_code = 4;
    string region = 5;
    string street_address = 6;
    uint64 sequence = 7;
}

message UpdateUserAddressRequest {
    string country = 1 [(validate.rules).string = {max_len: 200}];
    string locality = 2 [(validate.rules).string = {max_len: 200}];
    string postal_code = 3 [(validate.rules).string = {max_len: 200}];
    string region = 4 [(validate.rules).string = {max_len: 200}];
    string street_address = 5 [(validate.rules).string = {max_len: 200}];
}

message PasswordID {
    string id = 1;
}

message PasswordRequest {
    string password = 1 [(validate.rules).string = {min_len: 1, max_len: 72}];
}

message PasswordChange {
    string old_password = 1 [(validate.rules).string = {min_len: 1, max_len: 72}];
    string new_password = 2 [(validate.rules).string = {min_len: 1, max_len: 72}];
}

enum MfaType {
    MFATYPE_UNSPECIFIED = 0;
    MFATYPE_SMS = 1;
    MFATYPE_OTP = 2;
}

message VerifyMfaOtp {
    string code = 1;
}

message MultiFactors {
    repeated MultiFactor mfas = 1;
}

message MultiFactor {
    MfaType type = 1;
    MFAState state = 2;
}

message MfaOtpResponse {
    string user_id = 1;
    string url = 2;
    string secret = 3;
    MFAState state = 4;
}

enum MFAState {
    MFASTATE_UNSPECIFIED = 0;
    MFASTATE_NOT_READY = 1;
    MFASTATE_READY = 2;
    MFASTATE_REMOVED = 3;
}

message OIDCClientAuth {
    string client_id = 1;
    string client_secret = 2;
}

message MyProjectOrgSearchRequest {
    uint64 offset = 1;
    uint64 limit = 2;
    bool asc = 4;
    repeated MyProjectOrgSearchQuery queries = 5;
}

message MyProjectOrgSearchQuery {
    MyProjectOrgSearchKey key = 1 [(validate.rules).enum = {not_in: [0]}];;
    SearchMethod method = 2;
    string value = 3;
}

enum MyProjectOrgSearchKey {
    MYPROJECTORGSEARCHKEY_UNSPECIFIED = 0;
    MYPROJECTORGSEARCHKEY_ORG_NAME = 1;
}

message MyProjectOrgSearchResponse {
    uint64 offset = 1;
    uint64 limit = 2;
    uint64 total_result = 3;
    repeated Org result = 4;
}

message IsAdminResponse {
    bool is_admin = 1;
}

message Org {
    string id = 1;
    string name = 2;
}

message MyPermissions {
    repeated string permissions = 1;
}

enum SearchMethod {
    SEARCHMETHOD_EQUALS = 0;
    SEARCHMETHOD_STARTS_WITH = 1;
    SEARCHMETHOD_CONTAINS = 2;
}