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 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 (google.protobuf.Empty) {
    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 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"
    };
  }
}

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

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

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

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