IAuthService

앱 사용자의 계정 생성, 로그인, 계정 연동과 해제, 이용 제한 조회, 로그아웃, 계정 삭제를 제공하는 서비스입니다. 로그인 계열 메서드는 액세스 토큰을 바로 반환하지 않고 인가 코드(AuthorizationCode)를 반환하므로, 이 값을 ITokenService.IssueTokenAsync에 넘겨 액세스 토큰과 리프레시 토큰을 발급받으세요.

인터페이스: IAuthService
네임스페이스: Hive.Axyl.Auth
패키지: com.com2usplatform.hiveaxyl.auth

등록과 획득

Unity

using Hive.Axyl.Auth;
using Hive.Axyl.Core;
using Hive.Axyl.Core.Unity;   // HiveBootstrap

var config = CoreConfig.CreateBuilder("{appId}").Build();

HiveBootstrap.Initialize(config, builder =>
{
    builder.AddAuth();
});

IAuthService auth = HiveCore.Resolve<IAuthService>();

메서드 요약

'인증' 열의 의미는 인증 요구 표기를 참조하세요.

게스트 계정

메서드	인증	설명
CreateGuestAsync	불필요	새 게스트 계정을 만들고 인가 코드와 게스트 토큰을 받습니다.
LoginGuestAsync	불필요	저장해 둔 게스트 토큰으로 다시 로그인합니다.

유저네임 계정

메서드	인증	설명
CreateUsernameAsync	불필요	유저네임과 비밀번호로 새 계정을 만듭니다.
LoginUsernameAsync	불필요	유저네임과 비밀번호로 로그인합니다.
ChangeUsernamePasswordAsync	세션 필요	유저네임 계정의 로그인 비밀번호를 변경합니다.

외부 인증 제공자

메서드	인증	설명
GetProviderListAsync	불필요	이 앱에서 노출할 수 있는 로그인 수단 목록을 조회합니다.
ExchangeProviderTokenAsync	불필요	외부 인증 제공자가 발급한 인가 코드를 서버에서 사용자 식별자와 토큰으로 교환합니다.
LoginProviderAsync	불필요	외부 인증 제공자 계정으로 로그인하거나 가입합니다.
LinkProviderAsync	세션 필요	로그인한 Player ID에 로그인 수단을 추가로 연동합니다.
UnlinkProviderAsync	세션 필요	연동된 로그인 수단을 해제합니다.

커스텀 계정

메서드	인증	설명
LoginCustomProviderAsync	불필요	grant key로 커스텀 계정 로그인 또는 가입을 완료합니다.
LinkCustomProviderAsync	세션 필요	grant key로 커스텀 계정을 연동합니다.

세션과 계정 관리

메서드	인증	설명
LoginWithAccessTokenAsync	액세스 토큰 필요	저장해 둔 액세스 토큰으로 인증 상태를 복원하고 새 인가 코드를 받습니다.
LogoutPlayerAsync	세션 필요	요청을 보낸 기기의 로그인 세션을 서버에서 종료합니다.
GetBlockStatusAsync	세션 필요	현재 플레이어의 이용 제한 상태를 조회합니다.
WithdrawPlayerAsync	세션 필요	현재 앱의 플레이어 계정을 즉시 삭제합니다.

공통 파라미터

모든 메서드의 마지막 파라미터는 ApiCallContext? context = null입니다. 생략하면 기본값이 적용됩니다. 자세한 내용은 호출 컨텍스트를 참조하세요.

요청 본문을 받는 메서드의 request 파라미터는 모두 Required입니다. 아래 메서드 설명에서는 요청 타입만 표기하고 파라미터 표는 생략합니다. 각 요청 타입의 필드는 데이터 타입에서 확인하세요.

메서드

CreateGuestAsync

새 게스트 계정을 만들고 로그인 세션을 시작합니다. 응답으로 인가 코드와 함께 게스트 토큰이 발급되며, 이후 재로그인에는 LoginGuestAsync에서 이 게스트 토큰을 사용합니다.

Unity

Task<AuthCreateGuestResult> CreateGuestAsync(GuestCreateRequest request, ApiCallContext? context = null);

요청: GuestCreateRequest
응답: GuestCreateResponseData
인증: 불필요

결과 케이스 — AuthCreateGuestResult

결과 케이스	와이어 코드	설명
`Success`	—	게스트 계정 생성에 성공했습니다.
`InvalidGrantKey`	`invalid_grant_key`	grant key가 유효하지 않거나 만료됐습니다.
`GrantRequiredMissing`	`grant_required_missing`	이 인증 흐름에는 grant key가 필요하지만 전달되지 않았습니다.
`TerminateService`	`terminate_service`	서비스가 종료된 프로젝트입니다.
`InvalidClientId`	`invalid_client_id`	클라이언트 식별자가 등록되지 않았거나 이 프로젝트에 속하지 않습니다.
`IpBlocked`	`ip_blocked`	이 IP 주소에서의 접근이 제한됐습니다.
`AppNotFound`	`app_not_found`	앱 정보를 찾을 수 없습니다.
`ProviderConfigNotFound`	`provider_config_not_found`	이 앱에 설정된 로그인 수단이 없습니다.
`UnknownOutcome`	`UNKNOWN`	이 SDK 버전이 알지 못하는 새 결과입니다.
`Failure`	`FAILURE`	호출을 마치지 못했습니다. 공통 Failure 코드도 이 케이스로 분기합니다.

구현 절차는 게스트 계정 생성을 참조하세요.

LoginGuestAsync

저장해 둔 게스트 토큰으로 기존 게스트 계정에 다시 로그인합니다. 게스트 토큰은 재발급되지 않으며 기존 값이 계속 유효합니다.

Unity

Task<AuthLoginGuestResult> LoginGuestAsync(GuestLoginRequest request, ApiCallContext? context = null);

요청: GuestLoginRequest
응답: LoginResponseData
인증: 불필요

결과 케이스 — AuthLoginGuestResult

결과 케이스	와이어 코드	설명
`Success`	—	게스트 재로그인에 성공했습니다.
`InvalidGuestToken`	`invalid_guest_token`	게스트 토큰이 유효하지 않습니다.
`TerminateService`	`terminate_service`	서비스가 종료된 프로젝트입니다.
`InvalidClientId`	`invalid_client_id`	클라이언트 식별자가 등록되지 않았거나 이 프로젝트에 속하지 않습니다.
`IpBlocked`	`ip_blocked`	이 IP 주소에서의 접근이 제한됐습니다.
`AppNotFound`	`app_not_found`	앱 정보를 찾을 수 없습니다.
`UnknownOutcome`	`UNKNOWN`	이 SDK 버전이 알지 못하는 새 결과입니다.
`Failure`	`FAILURE`	호출을 마치지 못했습니다. 공통 Failure 코드도 이 케이스로 분기합니다.

구현 절차는 게스트 로그인을 참조하세요.

GetProviderListAsync

이 앱에서 노출할 수 있는 로그인 수단 목록을 조회합니다. 로그인 화면에 어떤 버튼을 보여 줄지 결정할 때 사용합니다.

국가는 서버가 요청 IP로 판별하며 앱 클라이언트가 지정할 수 없습니다. 국가에 따라 일부 로그인 수단이 목록에서 빠질 수 있고, 앱별 설정이 없으면 기본 설정이 적용됩니다.

Unity

Task<AuthGetProviderListResult> GetProviderListAsync(ApiCallContext? context = null);

요청: 없음
응답: ProviderListResponseData
인증: 불필요

결과 케이스 — AuthGetProviderListResult

결과 케이스	와이어 코드	설명
`Success`	—	조회에 성공했습니다.
`TerminateService`	`terminate_service`	서비스가 종료된 프로젝트입니다.
`AppNotFound`	`app_not_found`	앱 정보를 찾을 수 없습니다.
`ProviderConfigNotFound`	`provider_config_not_found`	이 앱에 설정된 로그인 수단이 없습니다.
`UnknownOutcome`	`UNKNOWN`	이 SDK 버전이 알지 못하는 새 결과입니다.
`Failure`	`FAILURE`	호출을 마치지 못했습니다. 공통 Failure 코드도 이 케이스로 분기합니다.

구현 절차는 지원하는 로그인 수단 조회를 참조하세요.

ExchangeProviderTokenAsync

외부 인증 제공자가 발급한 인가 코드를 Hive Axyl 인증 서버에서 교환해 ProviderUserId와 ProviderToken을 받습니다. 받은 값은 바꾸지 말고 LoginProviderAsync나 LinkProviderAsync에 그대로 넘기세요.

서버가 Hive 콘솔에 등록된 클라이언트 시크릿으로 제공자에 인증하므로, 이 메서드는 클라이언트 시크릿이 있는 웹 유형 클라이언트로 발급한 인가 코드만 교환합니다. Google Cloud Console이나 X Developer Portal에서 iOS·macOS·Android 앱용으로 만든 클라이언트처럼 클라이언트 시크릿이 없는 공개 클라이언트로 발급한 인가 코드는 이 메서드로 교환할 수 없습니다. 이 경우 앱 클라이언트가 직접 토큰 교환을 마친 뒤 LoginProviderAsync를 호출하세요.

Unity

Task<AuthExchangeProviderTokenResult> ExchangeProviderTokenAsync(ProviderTokenRequest request, ApiCallContext? context = null);

요청: ProviderTokenRequest
응답: ProviderTokenResponseData
인증: 불필요

결과 케이스 — AuthExchangeProviderTokenResult

결과 케이스	와이어 코드	설명
`Success`	—	교환에 성공했습니다.
`ProviderNotSupported`	`provider_not_supported`	지원하지 않는 로그인 수단입니다.
`ProviderTokenExchangeNotSupported`	`provider_token_exchange_not_supported`	서버 측 인가 코드 교환을 지원하지 않는 로그인 수단입니다.
`ProviderTokenError`	`provider_token_error`	로그인 수단의 토큰 또는 인가 코드 검증에 실패했습니다.
`TerminateService`	`terminate_service`	서비스가 종료된 프로젝트입니다.
`AppNotFound`	`app_not_found`	앱 정보를 찾을 수 없습니다.
`ProviderConfigNotFound`	`provider_config_not_found`	이 앱에 설정된 로그인 수단이 없습니다.
`ProviderClientInfoNotExists`	`provider_client_info_not_exists`	로그인 수단의 클라이언트 정보가 존재하지 않습니다.
`ProviderRequestFailed`	`provider_request_failed`	외부 인증 제공자에 보낸 요청이 실패했습니다.
`UnknownOutcome`	`UNKNOWN`	이 SDK 버전이 알지 못하는 새 결과입니다.
`Failure`	`FAILURE`	호출을 마치지 못했습니다. 공통 Failure 코드도 이 케이스로 분기합니다.

구현 절차는 외부 인증 코드 교환을 참조하세요.

LoginProviderAsync

외부 인증 제공자 계정으로 로그인하거나 가입합니다. 연결된 계정이 없으면 새 Player ID를 발급합니다.

Unity

Task<AuthLoginProviderResult> LoginProviderAsync(ProviderLoginRequest request, ApiCallContext? context = null);

요청: ProviderLoginRequest
응답: LoginResponseData
인증: 불필요

결과 케이스 — AuthLoginProviderResult

결과 케이스	와이어 코드	설명
`Success`	—	로그인 또는 가입에 성공했습니다.
`ProviderTokenError`	`provider_token_error`	로그인 수단의 토큰 또는 인가 코드 검증에 실패했습니다.
`TerminateService`	`terminate_service`	서비스가 종료된 프로젝트입니다.
`InvalidClientId`	`invalid_client_id`	클라이언트 식별자가 등록되지 않았거나 이 프로젝트에 속하지 않습니다.
`IpBlocked`	`ip_blocked`	이 IP 주소에서의 접근이 제한됐습니다.
`AppNotFound`	`app_not_found`	앱 정보를 찾을 수 없습니다.
`ProviderConfigNotFound`	`provider_config_not_found`	이 앱에 설정된 로그인 수단이 없습니다.
`ProviderClientInfoNotExists`	`provider_client_info_not_exists`	로그인 수단의 클라이언트 정보가 존재하지 않습니다.
`ProviderRequestFailed`	`provider_request_failed`	외부 인증 제공자에 보낸 요청이 실패했습니다.
`UnknownOutcome`	`UNKNOWN`	이 SDK 버전이 알지 못하는 새 결과입니다.
`Failure`	`FAILURE`	호출을 마치지 못했습니다. 공통 Failure 코드도 이 케이스로 분기합니다.

구현 절차는 외부 인증 제공자 로그인을 참조하세요.

LinkProviderAsync

로그인한 Player ID에 로그인 수단을 추가로 연동합니다.

Username을 연동하면 요청한 유저네임의 존재 여부와 소유자에 따라 흐름이 갈립니다. 존재하지 않으면 새로 만들어 연동하고, 다른 계정이 소유하고 있으면 UsernameAlreadyExists로 분기하며, 소유자가 없는 상태면 비밀번호 검증 후 다시 연동합니다. 첫 로그인 수단을 연동하면 게스트 토큰은 무효가 됩니다.

Unity

Task<AuthLinkProviderResult> LinkProviderAsync(ProviderLinkRequest request, ApiCallContext? context = null);

요청: ProviderLinkRequest
응답: ProviderLinkResponseData
인증: 세션 필요

결과 케이스 — AuthLinkProviderResult

결과 케이스	와이어 코드	설명
`Success`	—	연동에 성공했습니다.
`AppIdMismatch`	`app_id_mismatch`	`X-App-Id` 헤더의 앱이 인증 토큰과 같은 프로젝트에 속하지 않습니다.
`InvalidGatewayContext`	`invalid_gateway_context`	게이트웨이 인증 컨텍스트가 없거나 유효하지 않습니다.
`InvalidUsernameFormat`	`invalid_username_format`	유저네임 형식이 올바르지 않습니다.
`InvalidPasswordFormat`	`invalid_password_format`	비밀번호 형식이 올바르지 않습니다.
`ProviderTokenError`	`provider_token_error`	로그인 수단의 토큰 또는 인가 코드 검증에 실패했습니다.
`ProviderRequestFailed`	`provider_request_failed`	외부 인증 제공자에 보낸 요청이 실패했습니다.
`ProviderClientInfoNotExists`	`provider_client_info_not_exists`	로그인 수단의 클라이언트 정보가 존재하지 않습니다.
`UsernameVerifyFailed`	`username_verify_failed`	유저네임 또는 비밀번호가 올바르지 않습니다.
`UsernameAlreadyExists`	`username_already_exists`	이미 존재하는 유저네임입니다.
`TerminateService`	`terminate_service`	서비스가 종료된 프로젝트입니다.
`IpBlocked`	`ip_blocked`	이 IP 주소에서의 접근이 제한됐습니다.
`AppNotFound`	`app_not_found`	앱 정보를 찾을 수 없습니다.
`PlayerNotFound`	`player_not_found`	플레이어 정보를 찾을 수 없습니다.
`ProviderConfigNotFound`	`provider_config_not_found`	이 앱에 설정된 로그인 수단이 없습니다.
`ProviderTypeAlreadyExists`	`provider_type_already_exists`	같은 유형의 로그인 수단이 이미 연동되어 있습니다.
`ProviderOwnedByOther`	`provider_owned_by_other`	다른 플레이어에게 이미 연동된 로그인 수단입니다.
`ProviderAlreadyConnected`	`provider_already_connected`	이 플레이어에게 이미 연동된 로그인 수단입니다.
`UnknownOutcome`	`UNKNOWN`	이 SDK 버전이 알지 못하는 새 결과입니다.
`Failure`	`FAILURE`	호출을 마치지 못했습니다. 공통 Failure 코드도 이 케이스로 분기합니다.

케이스별 앱 대응은 계정 연동 처리 및 조회를, ProviderOwnedByOther 처리는 계정 연동 시 충돌 처리를 참조하세요.

UnlinkProviderAsync

연동된 로그인 수단을 해제합니다. 게스트는 해제할 수 없으며, 요청한 로그인 수단 외에 다른 일반 로그인 수단이 남아 있지 않으면 해제할 수 없습니다. 게스트와 커스텀 계정은 여기서 말하는 일반 로그인 수단에 포함되지 않습니다.

Unity

Task<AuthUnlinkProviderResult> UnlinkProviderAsync(ProviderUnlinkRequest request, ApiCallContext? context = null);

요청: ProviderUnlinkRequest
응답: VoidResponseData
인증: 세션 필요

결과 케이스 — AuthUnlinkProviderResult

결과 케이스	와이어 코드	설명
`Success`	—	연동 해제에 성공했습니다.
`AppIdMismatch`	`app_id_mismatch`	`X-App-Id` 헤더의 앱이 인증 토큰과 같은 프로젝트에 속하지 않습니다.
`InvalidGatewayContext`	`invalid_gateway_context`	게이트웨이 인증 컨텍스트가 없거나 유효하지 않습니다.
`ProviderNotSupported`	`provider_not_supported`	지원하지 않는 로그인 수단입니다.
`ProviderNotExist`	`provider_not_exist`	연동되어 있지 않은 로그인 수단입니다.
`TerminateService`	`terminate_service`	서비스가 종료된 프로젝트입니다.
`GuestUnlinkBlocked`	`guest_unlink_blocked`	게스트는 연동 해제할 수 있는 로그인 수단이 아닙니다.
`LastProviderUnlinkBlocked`	`last_provider_unlink_blocked`	마지막으로 남은 로그인 수단은 해제할 수 없습니다.
`IpBlocked`	`ip_blocked`	이 IP 주소에서의 접근이 제한됐습니다.
`AppNotFound`	`app_not_found`	앱 정보를 찾을 수 없습니다.
`UnknownOutcome`	`UNKNOWN`	이 SDK 버전이 알지 못하는 새 결과입니다.
`Failure`	`FAILURE`	호출을 마치지 못했습니다. 공통 Failure 코드도 이 케이스로 분기합니다.

구현 절차는 계정 연동 해제를 참조하세요.

LoginWithAccessTokenAsync

저장해 둔 액세스 토큰으로 플레이어 인증 상태를 복원합니다. 액세스 토큰을 새로 발급하지 않고 인가 코드를 반환하므로, 반환된 인가 코드로 ITokenService.IssueTokenAsync를 호출해 토큰을 다시 발급받으세요.

현재 세션이 아닌 특정 액세스 토큰으로 인증해야 하므로 ApiCallContext.WithAccessToken()으로 검증할 토큰을 실어 보냅니다.

Unity

Task<AuthLoginWithAccessTokenResult> LoginWithAccessTokenAsync(TokenLoginRequest request, ApiCallContext? context = null);

요청: TokenLoginRequest
응답: LoginResponseData
인증: 액세스 토큰 필요

호출 예시

Unity

var result = await auth.LoginWithAccessTokenAsync(
    new TokenLoginRequest
    {
        ClientId            = "{clientId}",
        CodeChallenge       = codeChallenge,
        CodeChallengeMethod = CodeChallengeMethod.S256,
    },
    ApiCallContext.WithAccessToken(storedAccessToken));

결과 케이스 — AuthLoginWithAccessTokenResult

결과 케이스	와이어 코드	설명
`Success`	—	인증 상태 복원에 성공했습니다.
`AppIdMismatch`	`app_id_mismatch`	`X-App-Id` 헤더의 앱이 인증 토큰과 같은 프로젝트에 속하지 않습니다.
`InvalidGatewayContext`	`invalid_gateway_context`	게이트웨이 인증 컨텍스트가 없거나 유효하지 않습니다.
`TerminateService`	`terminate_service`	서비스가 종료된 프로젝트입니다.
`InvalidClientId`	`invalid_client_id`	클라이언트 식별자가 등록되지 않았거나 이 프로젝트에 속하지 않습니다.
`IpBlocked`	`ip_blocked`	이 IP 주소에서의 접근이 제한됐습니다.
`AppNotFound`	`app_not_found`	앱 정보를 찾을 수 없습니다.
`PlayerNotFound`	`player_not_found`	플레이어 정보를 찾을 수 없습니다.
`UnknownOutcome`	`UNKNOWN`	이 SDK 버전이 알지 못하는 새 결과입니다.
`Failure`	`FAILURE`	호출을 마치지 못했습니다. 공통 Failure 코드도 이 케이스로 분기합니다.

구현 절차는 자동 로그인을 참조하세요.

LogoutPlayerAsync

요청을 보낸 기기의 로그인 세션을 서버에서 종료합니다. 같은 계정으로 로그인한 다른 기기의 세션은 유지됩니다. 게스트만 연결된 계정은 다시 로그인할 수단이 사라지므로 로그아웃할 수 없습니다.

이 메서드는 앱 클라이언트의 메모리 세션과 기기에 저장한 토큰을 지우지 않습니다. 이미 발급된 액세스 토큰은 만료될 때까지 유효하므로, 결과가 Success이면 앱이 보관한 세션과 토큰을 직접 정리하세요.

Unity

Task<AuthLogoutPlayerResult> LogoutPlayerAsync(ApiCallContext? context = null);

요청: 없음
응답: VoidResponseData
인증: 세션 필요

결과 케이스 — AuthLogoutPlayerResult

결과 케이스	와이어 코드	설명
`Success`	—	로그아웃에 성공했습니다.
`AppIdMismatch`	`app_id_mismatch`	`X-App-Id` 헤더의 앱이 인증 토큰과 같은 프로젝트에 속하지 않습니다.
`InvalidGatewayContext`	`invalid_gateway_context`	게이트웨이 인증 컨텍스트가 없거나 유효하지 않습니다.
`TerminateService`	`terminate_service`	서비스가 종료된 프로젝트입니다.
`AppNotFound`	`app_not_found`	앱 정보를 찾을 수 없습니다.
`PlayerNotFound`	`player_not_found`	플레이어 정보를 찾을 수 없습니다.
`GuestSignoutBlocked`	`guest_signout_blocked`	게스트만 연결된 계정은 로그아웃할 수 없습니다.
`UnknownOutcome`	`UNKNOWN`	이 SDK 버전이 알지 못하는 새 결과입니다.
`Failure`	`FAILURE`	호출을 마치지 못했습니다. 공통 Failure 코드도 이 케이스로 분기합니다.

저장한 인증 정보를 언제 삭제할지는 저장된 인증 정보 보존을, 구현 절차는 로그아웃을 참조하세요.

CreateUsernameAsync

유저네임과 비밀번호로 새 계정을 만듭니다. 같은 앱 안에 이미 존재하는 유저네임은 만들 수 없습니다.

Unity

Task<AuthCreateUsernameResult> CreateUsernameAsync(UsernameCreateRequest request, ApiCallContext? context = null);

요청: UsernameCreateRequest
응답: UsernameCreateResponseData
인증: 불필요

결과 케이스 — AuthCreateUsernameResult

결과 케이스	와이어 코드	설명
`Success`	—	계정 생성에 성공했습니다.
`InvalidGrantKey`	`invalid_grant_key`	grant key가 유효하지 않거나 만료됐습니다.
`GrantRequiredMissing`	`grant_required_missing`	이 인증 흐름에는 grant key가 필요하지만 전달되지 않았습니다.
`TerminateService`	`terminate_service`	서비스가 종료된 프로젝트입니다.
`InvalidClientId`	`invalid_client_id`	클라이언트 식별자가 등록되지 않았거나 이 프로젝트에 속하지 않습니다.
`IpBlocked`	`ip_blocked`	이 IP 주소에서의 접근이 제한됐습니다.
`AppNotFound`	`app_not_found`	앱 정보를 찾을 수 없습니다.
`ProviderConfigNotFound`	`provider_config_not_found`	이 앱에 설정된 로그인 수단이 없습니다.
`UsernameAlreadyExists`	`username_already_exists`	이미 존재하는 유저네임입니다.
`UnknownOutcome`	`UNKNOWN`	이 SDK 버전이 알지 못하는 새 결과입니다.
`Failure`	`FAILURE`	호출을 마치지 못했습니다. 공통 Failure 코드도 이 케이스로 분기합니다.

구현 절차는 유저네임 계정 생성을 참조하세요.

LoginUsernameAsync

유저네임과 비밀번호로 로그인합니다.

비밀번호 검증을 통과한 뒤 해당 자격 증명에 연결된 플레이어가 있으면 그 플레이어로 로그인합니다. 연동 해제 후 다시 로그인한 경우처럼 연결된 플레이어가 없으면 외부 인증 제공자 로그인과 마찬가지로 새 Player ID가 발급되며, 이때 응답의 IsBlock은 항상 false입니다. 기존 계정에 유저네임을 다시 연결하려면 LinkProviderAsync를 사용하세요.

Unity

Task<AuthLoginUsernameResult> LoginUsernameAsync(UsernameLoginRequest request, ApiCallContext? context = null);

요청: UsernameLoginRequest
응답: LoginResponseData
인증: 불필요

결과 케이스 — AuthLoginUsernameResult

결과 케이스	와이어 코드	설명
`Success`	—	로그인에 성공했습니다.
`UsernameVerifyFailed`	`username_verify_failed`	유저네임 또는 비밀번호가 올바르지 않습니다.
`TerminateService`	`terminate_service`	서비스가 종료된 프로젝트입니다.
`InvalidClientId`	`invalid_client_id`	클라이언트 식별자가 등록되지 않았거나 이 프로젝트에 속하지 않습니다.
`IpBlocked`	`ip_blocked`	이 IP 주소에서의 접근이 제한됐습니다.
`AppNotFound`	`app_not_found`	앱 정보를 찾을 수 없습니다.
`ProviderConfigNotFound`	`provider_config_not_found`	이 앱에 설정된 로그인 수단이 없습니다.
`UnknownOutcome`	`UNKNOWN`	이 SDK 버전이 알지 못하는 새 결과입니다.
`Failure`	`FAILURE`	호출을 마치지 못했습니다. 공통 Failure 코드도 이 케이스로 분기합니다.

구현 절차는 유저네임 로그인을 참조하세요.

ChangeUsernamePasswordAsync

유저네임 계정의 로그인 비밀번호를 변경합니다. 유저네임이 연동된 플레이어만 사용할 수 있으며, 유저네임을 어떤 경로로 연동했는지는 관계없습니다. 새 비밀번호는 현재 비밀번호와 달라야 합니다.

비밀번호를 변경하면 현재 기기를 포함한 모든 기기의 로그인 세션이 폐기됩니다. 변경에 성공하면 사용자가 새 비밀번호로 다시 로그인하도록 안내하세요.

Unity

Task<AuthChangeUsernamePasswordResult> ChangeUsernamePasswordAsync(UsernamePasswordChangeRequest request, ApiCallContext? context = null);

요청: UsernamePasswordChangeRequest
응답: VoidResponseData
인증: 세션 필요

결과 케이스 — AuthChangeUsernamePasswordResult

결과 케이스	와이어 코드	설명
`Success`	—	비밀번호 변경에 성공했습니다.
`AppIdMismatch`	`app_id_mismatch`	`X-App-Id` 헤더의 앱이 인증 토큰과 같은 프로젝트에 속하지 않습니다.
`InvalidGatewayContext`	`invalid_gateway_context`	게이트웨이 인증 컨텍스트가 없거나 유효하지 않습니다.
`SamePassword`	`same_password`	새 비밀번호가 현재 비밀번호와 같습니다.
`UsernameVerifyFailed`	`username_verify_failed`	유저네임 또는 비밀번호가 올바르지 않습니다.
`TerminateService`	`terminate_service`	서비스가 종료된 프로젝트입니다.
`IpBlocked`	`ip_blocked`	이 IP 주소에서의 접근이 제한됐습니다.
`AppNotFound`	`app_not_found`	앱 정보를 찾을 수 없습니다.
`ProviderNotExist`	`provider_not_exist`	연동되어 있지 않은 로그인 수단입니다.
`UsernameNotFound`	`username_not_found`	존재하지 않는 유저네임입니다.
`TokenRevokeFailed`	`token_revoke_failed`	플레이어의 토큰 폐기에 실패했습니다. 다시 시도해야 합니다.
`UnknownOutcome`	`UNKNOWN`	이 SDK 버전이 알지 못하는 새 결과입니다.
`Failure`	`FAILURE`	호출을 마치지 못했습니다. 공통 Failure 코드도 이 케이스로 분기합니다.

구현 절차는 비밀번호 변경을 참조하세요.

LoginCustomProviderAsync

grant key로 커스텀 계정 로그인 또는 가입을 완료하고 인가 코드를 발급받습니다. grant key를 발급할 때 사용한 App ID와 요청의 App ID가 같아야 합니다.

Unity

Task<AuthLoginCustomProviderResult> LoginCustomProviderAsync(CustomLoginRequest request, ApiCallContext? context = null);

요청: CustomLoginRequest
응답: LoginResponseData
인증: 불필요

결과 케이스 — AuthLoginCustomProviderResult

결과 케이스	와이어 코드	설명
`Success`	—	로그인 또는 가입에 성공했습니다.
`InvalidGrantKey`	`invalid_grant_key`	grant key가 유효하지 않거나 만료됐습니다.
`ProviderNotSupported`	`provider_not_supported`	지원하지 않는 로그인 수단입니다.
`TerminateService`	`terminate_service`	서비스가 종료된 프로젝트입니다.
`InvalidClientId`	`invalid_client_id`	클라이언트 식별자가 등록되지 않았거나 이 프로젝트에 속하지 않습니다.
`IpBlocked`	`ip_blocked`	이 IP 주소에서의 접근이 제한됐습니다.
`AppNotFound`	`app_not_found`	앱 정보를 찾을 수 없습니다.
`ProviderConfigNotFound`	`provider_config_not_found`	이 앱에 설정된 로그인 수단이 없습니다.
`UnknownOutcome`	`UNKNOWN`	이 SDK 버전이 알지 못하는 새 결과입니다.
`Failure`	`FAILURE`	호출을 마치지 못했습니다. 공통 Failure 코드도 이 케이스로 분기합니다.

구현 절차는 커스텀 계정 로그인을 참조하세요.

LinkCustomProviderAsync

grant key로 현재 로그인한 플레이어에게 커스텀 계정을 연동합니다. grant key를 발급할 때 사용한 App ID와 Player ID가 요청과 같아야 합니다. 커스텀 계정만 연동할 수 있고 일반 로그인 수단과 게스트는 차단됩니다.

Unity

Task<AuthLinkCustomProviderResult> LinkCustomProviderAsync(CustomLinkRequest request, ApiCallContext? context = null);

요청: CustomLinkRequest
응답: ProviderLinkResponseData
인증: 세션 필요

결과 케이스 — AuthLinkCustomProviderResult

결과 케이스	와이어 코드	설명
`Success`	—	연동에 성공했습니다.
`AppIdMismatch`	`app_id_mismatch`	`X-App-Id` 헤더의 앱이 인증 토큰과 같은 프로젝트에 속하지 않습니다.
`InvalidGatewayContext`	`invalid_gateway_context`	게이트웨이 인증 컨텍스트가 없거나 유효하지 않습니다.
`InvalidGrantKey`	`invalid_grant_key`	grant key가 유효하지 않거나 만료됐습니다.
`PlayerIdDoesNotMatch`	`player_id_does_not_match`	grant key를 발급할 때 사용한 Player ID와 일치하지 않습니다.
`ProviderNotSupported`	`provider_not_supported`	지원하지 않는 로그인 수단입니다.
`ProviderTypeAlreadyExists`	`provider_type_already_exists`	같은 유형의 로그인 수단이 이미 연동되어 있습니다.
`ProviderOwnedByOther`	`provider_owned_by_other`	다른 플레이어에게 이미 연동된 로그인 수단입니다.
`ProviderAlreadyConnected`	`provider_already_connected`	이 플레이어에게 이미 연동된 로그인 수단입니다.
`TerminateService`	`terminate_service`	서비스가 종료된 프로젝트입니다.
`IpBlocked`	`ip_blocked`	이 IP 주소에서의 접근이 제한됐습니다.
`AppNotFound`	`app_not_found`	앱 정보를 찾을 수 없습니다.
`PlayerNotFound`	`player_not_found`	플레이어 정보를 찾을 수 없습니다.
`ProviderConfigNotFound`	`provider_config_not_found`	이 앱에 설정된 로그인 수단이 없습니다.
`UnknownOutcome`	`UNKNOWN`	이 SDK 버전이 알지 못하는 새 결과입니다.
`Failure`	`FAILURE`	호출을 마치지 못했습니다. 공통 Failure 코드도 이 케이스로 분기합니다.

구현 절차는 커스텀 계정 연동을 참조하세요.

GetBlockStatusAsync

현재 플레이어의 이용 제한 상태를 조회합니다. 이용 제한은 오류가 아니라 업무 데이터로 반환되므로 제재 대상이어도 Success로 분기합니다.

제재 안내 메시지는 Accept-Language 헤더의 언어로 현지화되며, 그 언어의 문구가 비어 있거나 앱이 지원하지 않는 언어를 요청하면 앱의 기본 언어로 반환됩니다. 요청 언어는 SetLanguage로 지정합니다.

Unity

Task<AuthGetBlockStatusResult> GetBlockStatusAsync(ApiCallContext? context = null);

요청: 없음
응답: BlockStatusResponseData
인증: 세션 필요

결과 케이스 — AuthGetBlockStatusResult

결과 케이스	와이어 코드	설명
`Success`	—	조회에 성공했습니다. 제재 여부는 `Data.IsBlocked`로 확인합니다.
`AppIdMismatch`	`app_id_mismatch`	`X-App-Id` 헤더의 앱이 인증 토큰과 같은 프로젝트에 속하지 않습니다.
`InvalidGatewayContext`	`invalid_gateway_context`	게이트웨이 인증 컨텍스트가 없거나 유효하지 않습니다.
`TerminateService`	`terminate_service`	서비스가 종료된 프로젝트입니다.
`AppNotFound`	`app_not_found`	앱 정보를 찾을 수 없습니다.
`BlockTypeNotFound`	`block_type_not_found`	이용 제한 유형 기준 정보를 찾을 수 없습니다.
`BlockTypeContentNotFound`	`block_type_content_not_found`	이용 제한 유형은 있지만 기본 언어의 안내 문구를 찾을 수 없습니다.
`UnknownOutcome`	`UNKNOWN`	이 SDK 버전이 알지 못하는 새 결과입니다.
`Failure`	`FAILURE`	호출을 마치지 못했습니다. 공통 Failure 코드도 이 케이스로 분기합니다.

구현 절차는 이용 제한을 참조하세요.

WithdrawPlayerAsync

현재 앱에 속한 플레이어 계정을 즉시 삭제하며, 삭제한 계정은 복구할 수 없습니다. 모든 로그인 수단 연동과 게스트 토큰이 삭제되고, 유저네임 계정이 있으면 유저네임과 비밀번호 자격 증명도 함께 삭제됩니다. 이용 제한 데이터는 남습니다. 삭제한 뒤 같은 로그인 수단으로 다시 로그인해도 이전 계정은 복원되지 않고 새 Player ID가 발급됩니다.

계정을 삭제하기 전에 모든 기기의 로그인 세션을 폐기합니다. 세션 폐기에 실패하면 계정을 삭제하지 않고 TokenRevokeFailed를 반환하므로 다시 시도하세요. 세션이 이미 종료되었다면 다시 로그인한 뒤 시도하세요.

Unity

Task<AuthWithdrawPlayerResult> WithdrawPlayerAsync(ApiCallContext? context = null);

요청: 없음
응답: VoidResponseData
인증: 세션 필요

결과 케이스 — AuthWithdrawPlayerResult

결과 케이스	와이어 코드	설명
`Success`	—	계정 삭제에 성공했습니다.
`AppIdMismatch`	`app_id_mismatch`	`X-App-Id` 헤더의 앱이 인증 토큰과 같은 프로젝트에 속하지 않습니다.
`InvalidGatewayContext`	`invalid_gateway_context`	게이트웨이 인증 컨텍스트가 없거나 유효하지 않습니다.
`TerminateService`	`terminate_service`	서비스가 종료된 프로젝트입니다.
`AppNotFound`	`app_not_found`	앱 정보를 찾을 수 없습니다.
`PlayerNotFound`	`player_not_found`	플레이어 정보를 찾을 수 없습니다.
`TokenRevokeFailed`	`token_revoke_failed`	로그인 세션 폐기에 실패해 계정을 삭제하지 않았습니다. 다시 시도하세요.
`UnknownOutcome`	`UNKNOWN`	이 SDK 버전이 알지 못하는 새 결과입니다.
`Failure`	`FAILURE`	호출을 마치지 못했습니다. 공통 Failure 코드도 이 케이스로 분기합니다.

구현 절차는 계정 삭제를 참조하세요.

데이터 타입

여러 요청 타입이 공유하는 필드는 의미가 같습니다.

ClientId: Hive 콘솔이 프로젝트마다 발급하는 PKCE 클라이언트 식별자. 확인 방법은 Client ID를 참조하세요.
CodeChallenge: PKCE code challenge. 토큰을 발급할 때 이 값의 원본을 CodeVerifier로 제출합니다.
CodeChallengeMethod: PKCE 변환 방식. S256으로 고정
DeviceKey: 로그인 세션을 기기별로 구분하는 기기 식별자. 기기마다 다른 난수로 만들어 저장해 두고 다시 사용하며, 조건과 생성 예시는 deviceKey를 참조하세요.
Username: 영문자를 하나 이상 포함한 3~20자의 유저네임 식별자. 영문자, 숫자, ., _, -만 쓸 수 있으며 정규식은 ^(?=.*[A-Za-z])[A-Za-z0-9._-]{3,20}$입니다.
Password, CurrentPassword, NewPassword: 앱 클라이언트에서 SHA256(원본 비밀번호)로 변환한 비밀번호. 평문을 보내면 안 되며, 변환 결과는 소문자 16진수 64자인 ^[0-9a-f]{64}$ 형식이어야 합니다.
Meta: 서버가 가공하지 않은 원본 JSON 문자열로 함께 전달한 부가 정보

BlockDetail

이용 제한 상세 정보입니다.

필드	타입	필수 여부	설명
`Code`	`int`	Required	100~999 범위의 이용 제한 유형 코드입니다. Hive 콘솔의 이용 제한 유형에 등록한 코드와 같은 값입니다.
`Name`	`string`	Required	현지화된 이용 제한 유형 이름입니다.
`Message`	`string`	Required	사용자에게 보여 줄 현지화된 안내 메시지입니다.
`StartAt`	`DateTimeOffset`	Required	이용 제한 시작 시각입니다. UTC 기준입니다.
`EndAt`	`DateTimeOffset?`	Optional	이용 제한 종료 시각입니다. UTC 기준이며, 영구 제한이면 `null`입니다.

BlockStatusResponseData

필드	타입	필수 여부	설명
`IsBlocked`	`bool`	Required	이용 제한 대상 여부입니다.
`Block`	BlockDetail?	Optional	이용 제한 상세입니다. `IsBlocked`가 `false`이면 `null`입니다.
`Meta`	`string?`	Optional	서버가 함께 전달한 부가 정보입니다.

CustomLinkRequest

필드	타입	필수 여부	설명
`GrantKey`	`string`	Required	`authType=CUSTOM_LINK`로 발급받은 사전 인가 키입니다. 유효 시간 60초, 1회용입니다.

CustomLoginRequest

필드	타입	필수 여부	설명
`DeviceKey`	`string`	Required	기기 식별자입니다.
`GrantKey`	`string`	Required	`authType=CUSTOM_LOGIN`으로 발급받은 사전 인가 키입니다. 유효 시간 60초, 1회용입니다.
`ClientId`	`string`	Required	PKCE 클라이언트 식별자입니다.
`CodeChallenge`	`string`	Required	PKCE code challenge입니다.
`CodeChallengeMethod`	CodeChallengeMethod	Required	`S256`으로 고정합니다.

GuestCreateRequest

필드	타입	필수 여부	설명
`GrantKey`	`string?`	Optional	앱 서버가 발급받아 전달한 사전 인가 키입니다. 유효 시간 60초, 1회용입니다. Hive 콘솔에서 추가 보안을 켰다면 반드시 보내야 합니다. 추가 보안이 꺼져 있어도 보낼 수 있으며, 보낸 값은 설정과 관계없이 항상 검증되고 소비됩니다. 추가 보안을 켜는 순간 요청이 거부되지 않도록 항상 보내는 것을 권장합니다.
`ClientId`	`string`	Required	PKCE 클라이언트 식별자입니다.
`CodeChallenge`	`string`	Required	PKCE code challenge입니다.
`CodeChallengeMethod`	CodeChallengeMethod	Required	`S256`으로 고정합니다.
`DeviceKey`	`string`	Required	기기 식별자입니다.

GuestCreateResponseData

필드	타입	필수 여부	설명
`PlayerId`	`long`	Required	생성된 Player ID입니다.
`CreatedAt`	`DateTimeOffset`	Required	계정 생성 시각입니다.
`AuthorizationCode`	`string`	Required	토큰 발급에 사용할 인가 코드입니다. 유효 시간은 180초입니다.
`GuestToken`	`string`	Required	게스트 재로그인에 사용할 영문자·숫자 32자 토큰입니다. 기기에 안전하게 보관하세요.
`Meta`	`string?`	Optional	서버가 함께 전달한 부가 정보입니다.

GuestLoginRequest

필드	타입	필수 여부	설명
`GuestPlayerId`	`long`	Required	게스트 계정을 만들 때 발급받은 Player ID입니다.
`GuestToken`	`string`	Required	이전에 발급받은 게스트 토큰입니다.
`ClientId`	`string`	Required	PKCE 클라이언트 식별자입니다.
`CodeChallenge`	`string`	Required	PKCE code challenge입니다.
`CodeChallengeMethod`	CodeChallengeMethod	Required	`S256`으로 고정합니다.
`DeviceKey`	`string`	Required	기기 식별자입니다.

LoginResponseData

로그인 계열 메서드가 공통으로 반환하는 응답입니다.

필드	타입	필수 여부	설명
`PlayerId`	`long`	Required	로그인한 Player ID입니다.
`CreatedAt`	`DateTimeOffset`	Required	계정 생성 시각입니다.
`AuthorizationCode`	`string`	Required	토큰 발급에 사용할 인가 코드입니다. 유효 시간은 180초입니다.
`ProviderList`	IReadOnlyList<ProviderInfo>	Required	이 계정에 연결된 로그인 수단 목록입니다. 게스트가 아닌 로그인 수단이 하나라도 연동되면 `Guest`는 목록에서 제외되며, 다른 로그인 수단이 전혀 없는 순수 게스트일 때만 `Guest`가 포함됩니다.
`IsBlock`	`bool`	Required	이용 제한 대상 여부입니다. `true`여도 로그인은 성공하므로 실패로 처리하지 말고 이용 제한 안내를 표시하는 신호로 사용하세요. 사유와 기간 등 상세 정보는 GetBlockStatusAsync로 조회합니다.
`Meta`	`string?`	Optional	서버가 함께 전달한 부가 정보입니다.

ProviderInfo

플레이어에게 연결된 로그인 수단 정보입니다.

필드	타입	필수 여부	설명
`ProviderUserId`	`string`	Required	연결된 계정의 사용자 식별자입니다.
`ProviderId`	Provider	Required	연결된 로그인 수단입니다.
`ProviderIndex`	`int`	Required	로그인 수단을 숫자로 나타낸 식별자입니다.

ProviderItem

사용할 수 있는 로그인 수단 항목입니다.

필드	타입	필수 여부	설명
`ProviderIndex`	`int`	Required	로그인 수단을 숫자로 나타낸 식별자입니다.
`ProviderId`	Provider	Required	로그인 수단 식별자입니다.

ProviderLinkRequest

필드	타입	필수 여부	설명
`ProviderId`	Provider	Required	연동할 로그인 수단입니다. `Google`, `SigninApple`, `GooglePlayGames`, `Steam`, `X`, `Username`만 허용합니다. `Guest`처럼 허용하지 않는 값을 넣으면 `Problem.ExternalCode`가 `invalid_parameter`인 `Failure`로 분기합니다.
`ProviderUserId`	`string`	Required	로그인 수단의 사용자 식별자입니다. `Username`이면 공유 필드 `Username`과 같은 형식의 유저네임 문자열이며, 이미 존재하면 연동하고 없으면 새로 만들어 연동합니다. 형식을 어기면 `InvalidUsernameFormat`으로 분기합니다.
`ProviderToken`	`string`	Required	로그인 수단의 인증 결과 토큰입니다. `Username`이면 공유 필드 `Password`와 같은 형식의 `SHA256(원본 비밀번호)` 값이며, 이미 존재하는 유저네임이면 비밀번호를 검증하고 없으면 새 계정의 비밀번호로 설정합니다. 형식을 어기면 `InvalidPasswordFormat`으로 분기합니다.

ProviderLinkResponseData

필드	타입	필수 여부	설명
`PlayerId`	`long`	Required	로그인 수단을 연결한 Player ID입니다.
`ProviderUserId`	`string`	Required	연결된 계정의 사용자 식별자입니다.
`ProviderIndex`	`int`	Required	로그인 수단을 숫자로 나타낸 식별자입니다.
`ProviderId`	Provider	Required	연결된 로그인 수단입니다.
`Meta`	`string?`	Optional	서버가 함께 전달한 부가 정보입니다.

ProviderListResponseData

필드	타입	필수 여부	설명
`ProviderList`	IReadOnlyList<ProviderItem>	Required	이 앱에서 사용할 수 있는 로그인 수단 목록입니다. 앱 설정과 국가 조건이 적용된 결과입니다.
`Meta`	`string?`	Optional	서버가 함께 전달한 부가 정보입니다.

ProviderLoginRequest

필드	타입	필수 여부	설명
`DeviceKey`	`string`	Required	기기 식별자입니다.
`ProviderId`	Provider	Required	로그인할 로그인 수단입니다. `Google`, `SigninApple`, `GooglePlayGames`, `Steam`, `X`만 허용합니다. `Guest`와 `Username`은 허용하지 않으며, 유저네임 로그인은 LoginUsernameAsync를 사용합니다.
`ProviderUserId`	`string`	Required	로그인 수단의 사용자 식별자입니다. `Steam`이면 SteamID64이며, iOS, Android의 웹 로그인에서는 `openid.claimed_id`의 마지막 경로 값입니다.
`ProviderToken`	`string`	Required	검증에 사용할 로그인 수단의 토큰 또는 인증 결과입니다. 로그인 수단별로 넣는 값은 아래 목록을 참조하세요.
`ClientId`	`string`	Required	PKCE 클라이언트 식별자입니다.
`CodeChallenge`	`string`	Required	PKCE code challenge입니다.
`CodeChallengeMethod`	CodeChallengeMethod	Required	`S256`으로 고정합니다.

ProviderToken에 넣는 값은 로그인 수단마다 다릅니다. ExchangeProviderTokenAsync로 인가 코드를 교환했다면 응답의 ProviderToken을 그대로 넣으세요.

Google, SigninApple: JWT 형식의 id_token
GooglePlayGames, X: access_token
Windows, macOS의 Steam: GetAuthTicketForWebApiAsync()로 받은 세션 티켓의 16진 문자열
iOS, Android의 Steam: Steam이 return_to 주소로 돌려준 쿼리 문자열 전체

iOS, Android에서 Steam이 돌려준 쿼리 문자열은 받은 그대로 보내세요. openid. 파라미터를 다시 조립하거나 다시 인코딩하면 openid.sig 서명 검증에 실패합니다.

ProviderTokenRequest

필드	타입	필수 여부	설명
`ProviderId`	Provider	Required	인가 코드 교환을 지원하는 로그인 수단입니다. `Google`, `SigninApple`, `GooglePlayGames`, `X`만 허용합니다. 교환을 지원하지 않는 값이면 `ProviderTokenExchangeNotSupported`로, 정의되지 않은 값이면 `ProviderNotSupported`로 분기합니다.
`ProviderCode`	`string`	Required	외부 인증 제공자가 발급한 인가 코드입니다.
`RedirectUri`	`string?`	Optional	코드 교환에 사용할 리디렉션 URI입니다. `Google`, `GooglePlayGames`, `X`에서는 필요합니다. `SigninApple`은 Service ID를 사용하는 웹 로그인으로 받은 인가 코드를 교환할 때만 필요하며, 네이티브 SDK로 받은 인가 코드면 비워 두세요. 인가 요청에 사용한 값과 한 글자도 달라서는 안 되며, 다르면 외부 인증 제공자가 교환을 거부합니다. 인가 요청의 리디렉션 URI에 `?relayTo=...`를 붙여 Hive Axyl 중계 주소를 거쳤다면 그 쿼리까지 포함한 문자열을 그대로 보내세요.
`CodeVerifier`	`string?`	Optional	PKCE code verifier입니다. `X`에서는 필요합니다. `Google`은 인가 요청에 PKCE `code_challenge`를 사용한 경우에만 함께 보냅니다.

ProviderTokenResponseData

필드	타입	필수 여부	설명
`ProviderUserId`	`string`	Required	교환으로 확인한 사용자 식별자입니다.
`ProviderToken`	`string`	Required	교환으로 받은 토큰입니다. 로그인이나 연동 요청에 그대로 넘깁니다.
`ProviderId`	Provider	Required	교환한 로그인 수단입니다.
`Meta`	`string?`	Optional	서버가 함께 전달한 부가 정보입니다.

ProviderUnlinkRequest

필드	타입	필수 여부	설명
`ProviderId`	Provider	Required	연동을 해제할 로그인 수단입니다. `Guest`는 해제할 수 없습니다. `Guest`를 넣으면 `GuestUnlinkBlocked`로, 정의되지 않은 값을 넣으면 `ProviderNotSupported`로 분기합니다.

TokenLoginRequest

필드	타입	필수 여부	설명
`ClientId`	`string`	Required	PKCE 클라이언트 식별자입니다.
`CodeChallenge`	`string`	Required	PKCE code challenge입니다.
`CodeChallengeMethod`	CodeChallengeMethod	Required	`S256`으로 고정합니다.

UsernameCreateRequest

필드	타입	필수 여부	설명
`GrantKey`	`string?`	Optional	앱 서버가 발급받아 전달한 사전 인가 키입니다. 유효 시간 60초, 1회용입니다. Hive 콘솔에서 추가 보안을 켰다면 반드시 보내야 합니다. 추가 보안이 꺼져 있어도 보낼 수 있으며, 보낸 값은 설정과 관계없이 항상 검증되고 소비됩니다. 추가 보안을 켜는 순간 요청이 거부되지 않도록 항상 보내는 것을 권장합니다.
`DeviceKey`	`string`	Required	기기 식별자입니다.
`Username`	`string`	Required	유저네임 식별자입니다.
`Password`	`string`	Required	비밀번호입니다. 앱 클라이언트에서 `SHA256(원본 비밀번호)`로 변환해 보내며 평문을 보내면 안 됩니다.
`ClientId`	`string`	Required	PKCE 클라이언트 식별자입니다.
`CodeChallenge`	`string`	Required	PKCE code challenge입니다.
`CodeChallengeMethod`	CodeChallengeMethod	Required	`S256`으로 고정합니다.

UsernameCreateResponseData

필드	타입	필수 여부	설명
`PlayerId`	`long`	Required	생성된 Player ID입니다.
`CreatedAt`	`DateTimeOffset`	Required	계정 생성 시각입니다.
`AuthorizationCode`	`string`	Required	토큰 발급에 사용할 인가 코드입니다. 유효 시간은 180초입니다.
`Meta`	`string?`	Optional	서버가 함께 전달한 부가 정보입니다.

UsernameLoginRequest

필드	타입	필수 여부	설명
`DeviceKey`	`string`	Required	기기 식별자입니다.
`Username`	`string`	Required	유저네임 식별자입니다.
`Password`	`string`	Required	비밀번호입니다. 앱 클라이언트에서 `SHA256(원본 비밀번호)`로 변환해 보내며 평문을 보내면 안 됩니다.
`ClientId`	`string`	Required	PKCE 클라이언트 식별자입니다.
`CodeChallenge`	`string`	Required	PKCE code challenge입니다.
`CodeChallengeMethod`	CodeChallengeMethod	Required	`S256`으로 고정합니다.

UsernamePasswordChangeRequest

필드	타입	필수 여부	설명
`CurrentPassword`	`string`	Required	현재 비밀번호입니다. 앱 클라이언트에서 `SHA256(원본 비밀번호)`로 변환해 보내며 평문을 보내면 안 됩니다.
`NewPassword`	`string`	Required	새 비밀번호입니다. 앱 클라이언트에서 `SHA256(원본 비밀번호)`로 변환해 보내며 현재 비밀번호와 달라야 합니다. 같으면 `SamePassword`로 분기합니다.

VoidResponseData

반환할 데이터가 없는 메서드의 응답입니다.

필드	타입	필수 여부	설명
`Meta`	`string?`	Optional	서버가 함께 전달한 부가 정보입니다.

열거형

앱 코드에는 C# 멤버 이름을 입력하세요. 와이어 값은 서버와 주고받는 문자열입니다.

CodeChallengeMethod

PKCE 변환 방식입니다. RFC 7636의 S256만 지원합니다.

C# 멤버	와이어 값	설명
`Unspecified`	`CODE_CHALLENGE_METHOD_UNSPECIFIED`	값을 지정하지 않은 기본값입니다. 요청에 사용하지 마세요.
`S256`	`S256`	SHA-256 기반 변환입니다. 요청에는 항상 이 값을 사용합니다.

Provider

로그인 수단 식별자입니다.

C# 멤버	와이어 값	설명
`Unspecified`	`PROVIDER_UNSPECIFIED`	값을 지정하지 않은 기본값입니다. 요청에 사용하지 마세요.
`Guest`	`GUEST`	게스트 계정입니다.
`Google`	`GOOGLE`	Google 계정입니다.
`SigninApple`	`SIGNIN_APPLE`	Sign in with Apple입니다.
`GooglePlayGames`	`GOOGLE_PLAY_GAMES`	Google Play Games입니다.
`Steam`	`STEAM`	Steam 계정입니다.
`X`	`X`	X(Twitter) 계정입니다.
`Username`	`USERNAME`	유저네임 계정입니다.
`CustomProvider`	`CUSTOM_PROVIDER`	커스텀 계정입니다.