zitadel/pkg/grpc/auth/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";
import "proto/message.proto";

package caos.zitadel.auth.api.v1;

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

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

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

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

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

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

  rpc GetMyUserProfile(google.protobuf.Empty) returns (UserProfileView) {
    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 ChangeMyUserName(ChangeUserNameRequest) returns (google.protobuf.Empty) {
    option (google.api.http) = {
      put: "/users/me/username"
      body: "*"
    };

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

  rpc GetMyUserEmail(google.protobuf.Empty) returns (UserEmailView) {
    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 (UserPhoneView) {
    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 RemoveMyUserPhone(google.protobuf.Empty) returns (google.protobuf.Empty) {
    option (google.api.http) = {
      delete: "/users/me/phone"
    };

    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 (UserAddressView) {
    option (google.api.http) = {
      get: "/users/me/address"
    };

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

  rpc GetMyUserChanges(ChangesRequest) returns (Changes) {
    option (google.api.http) = {
      get: "/users/me/changes"
    };

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

  rpc GetMyPasswordComplexityPolicy(google.protobuf.Empty) returns (PasswordComplexityPolicy) {
    option (google.api.http) = {
            get: "/policies/passwords/complexity"
        };

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

  //ExternalIDP
  rpc SearchMyExternalIDPs(ExternalIDPSearchRequest) returns (ExternalIDPSearchResponse) {
    option (google.api.http) = {
      post: "/users/me/externalidps/_search"
      body: "*"
    };

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

  rpc RemoveMyExternalIDP(ExternalIDPRemoveRequest) returns (google.protobuf.Empty) {
    option (google.api.http) = {
      delete: "/users/me/externalidps/{idp_config_id}/{external_user_id}"
    };

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

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

  rpc VerifyMfaOTP(VerifyMfaOtp) returns (google.protobuf.Empty) {
    option (google.api.http) = {
      put: "/users/me/mfas/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/mfas/otp"
    };

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

  rpc SearchMyUserGrant(UserGrantSearchRequest) returns (UserGrantSearchResponse) {
    option (google.api.http) = {
      post: "/usergrants/me/_search"
      body: "*"
    };
    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"
    };
  }

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

  rpc GetMyProjectPermissions(google.protobuf.Empty) returns (MyPermissions) {
    option (google.api.http) = {
      get: "/permissions/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;
  string login_name = 7;
  string display_name = 8;
}

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

message UserView {
  string id = 1;
  UserState state = 2;
  google.protobuf.Timestamp creation_date = 3;
  google.protobuf.Timestamp change_date = 4;
  uint64 sequence = 5;
  repeated string login_names = 6;
  string preferred_login_name = 7;
  google.protobuf.Timestamp last_login = 8;
  string resource_owner = 9;
  string user_name = 10;

  oneof user {
    option (validate.required) = true;

    HumanView human = 11;
    MachineView machine = 12;
  }
}

message MachineView {
  google.protobuf.Timestamp last_key_added = 1;

  string name = 2;
  string description = 3;
}

message MachineKeyView {
  string id = 1;
  MachineKeyType type = 2;
  uint64 sequence = 3;

  google.protobuf.Timestamp creation_date = 4;
  google.protobuf.Timestamp expiration_date = 5;
}

enum MachineKeyType {
  MACHINEKEY_UNSPECIFIED = 0;
  MACHINEKEY_JSON = 1;
}

message HumanView {
  google.protobuf.Timestamp password_changed = 1;
  string first_name = 2;
  string last_name = 3;
  string display_name = 4;
  string nick_name = 5;
  string preferred_language = 6;
  Gender gender = 7;
  string email = 8;
  bool is_email_verified = 9;
  string phone = 10;
  bool is_phone_verified = 11;
  string country = 12;
  string locality = 13;
  string postal_code = 14;
  string region = 15;
  string street_address = 16;
}

enum UserState {
  USERSTATE_UNSPECIFIED = 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 first_name = 2;
  string last_name = 3;
  string nick_name = 4;
  string display_name = 5;
  string preferred_language = 6;
  Gender gender = 7;
  uint64 sequence = 8;
  google.protobuf.Timestamp creation_date = 9;
  google.protobuf.Timestamp change_date = 10;
}

message UserProfileView {
  string id = 1;
  string first_name = 2;
  string last_name = 3;
  string nick_name = 4;
  string display_name = 5;
  string preferred_language = 6;
  Gender gender = 7;
  uint64 sequence = 8;
  google.protobuf.Timestamp creation_date = 9;
  google.protobuf.Timestamp change_date = 10;
  repeated string login_names = 11;
  string preferred_login_name = 12;
}

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.max_len = 200];
  string preferred_language = 4 [(validate.rules).string = {min_len: 1, max_len: 200}];
  Gender gender = 5;
}

message ChangeUserNameRequest {
  string user_name = 1 [(validate.rules).string.pattern = "^[^[:space:]]{1,200}$"];
}

message UserEmail {
  string id = 1;
  string email = 2;
  bool isEmailVerified = 3;
  uint64 sequence = 4;
  google.protobuf.Timestamp creation_date = 5;
  google.protobuf.Timestamp change_date = 6;
}

message UserEmailView {
  string id = 1;
  string email = 2;
  bool isEmailVerified = 3;
  uint64 sequence = 4;
  google.protobuf.Timestamp creation_date = 5;
  google.protobuf.Timestamp change_date = 6;
}

message VerifyMyUserEmailRequest {
  string code = 1 [(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;
  google.protobuf.Timestamp creation_date = 5;
  google.protobuf.Timestamp change_date = 6;
}

message UserPhoneView {
  string id = 1;
  string phone = 2;
  bool is_phone_verified = 3;
  uint64 sequence = 4;
  google.protobuf.Timestamp creation_date = 5;
  google.protobuf.Timestamp change_date = 6;
}

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;
  google.protobuf.Timestamp creation_date = 8;
  google.protobuf.Timestamp change_date = 9;
}

message UserAddressView {
  string id = 1;
  string country = 2;
  string locality = 3;
  string postal_code = 4;
  string region = 5;
  string street_address = 6;
  uint64 sequence = 7;
  google.protobuf.Timestamp creation_date = 8;
  google.protobuf.Timestamp change_date = 9;
}

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 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 [(validate.rules).string = {min_len: 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 UserGrantSearchRequest {
  uint64 offset = 1;
  uint64 limit = 2;
  UserGrantSearchKey sorting_column = 3 [(validate.rules).enum = {not_in: [0]}];;
  bool asc = 4;
  repeated UserGrantSearchQuery queries = 5;
}

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

enum UserGrantSearchKey {
  UserGrantSearchKey_UNKNOWN = 0;
  UserGrantSearchKey_ORG_ID = 1;
  UserGrantSearchKey_PROJECT_ID = 2;
}

message UserGrantSearchResponse {
  uint64 offset = 1;
  uint64 limit = 2;
  uint64 total_result = 3;
  repeated UserGrantView result = 4;
  uint64 processed_sequence = 5;
  google.protobuf.Timestamp view_timestamp = 6;
}

message UserGrantView {
  string OrgId = 1;
  string ProjectId = 2;
  string UserId = 3;
  repeated string Roles = 4;
  string OrgName = 5;
  string GrantId = 6;
}

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 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;
  SEARCHMETHOD_EQUALS_IGNORE_CASE = 3;
  SEARCHMETHOD_STARTS_WITH_IGNORE_CASE = 4;
  SEARCHMETHOD_CONTAINS_IGNORE_CASE = 5;
}

message ChangesRequest {
  uint64 limit= 1;
  uint64 sequence_offset = 2;
  bool asc = 3;
}

message Changes {
  repeated Change changes = 1;
  uint64 offset = 2;
  uint64 limit = 3;
}

message Change {
  google.protobuf.Timestamp change_date = 1;
  caos.zitadel.api.v1.LocalizedMessage event_type = 2;
  uint64 sequence = 3;
  string editor_id = 4;
  string editor = 5;
  google.protobuf.Struct data = 6;
}

message PasswordComplexityPolicy {
  string id = 1;
  string description = 2;
  google.protobuf.Timestamp creation_date = 3;
  google.protobuf.Timestamp change_date = 4;
  uint64 min_length = 5;
  bool has_lowercase = 6;
  bool has_uppercase = 7;
  bool has_number = 8;
  bool has_symbol = 9;
  uint64 sequence = 10;
  bool is_default = 11;
}

message ExternalIDPResponse {
  string idp_config_id = 1;
  string user_id = 2;
  string display_name = 3;
}

message ExternalIDPRemoveRequest {
  string idp_config_id = 1;
  string external_user_id = 2;
}

message ExternalIDPSearchRequest {
  uint64 offset = 1;
  uint64 limit = 2;
}

message ExternalIDPSearchResponse {
  uint64 offset = 1;
  uint64 limit = 2;
  uint64 total_result = 3;
  repeated ExternalIDPView result = 4;
  uint64 processed_sequence = 5;
  google.protobuf.Timestamp view_timestamp = 6;
}

message ExternalIDPView {
  string user_id = 1;
  string idp_config_id = 2;
  string external_user_id = 3;
  string idp_name = 4;
  string external_user_display_name = 5;
  google.protobuf.Timestamp creation_date = 6;
  google.protobuf.Timestamp change_date = 7;
}