게스트 계정 생성

게스트 계정을 생성할 때는 ClientId, PKCE, DeviceKey를 사용합니다. 추가 보안을 적용하는 경우에는 GrantKey도 사용합니다.

1. 호출 파라미터 준비

게스트 계정 생성에 필요한 파라미터를 준비합니다.

ClientId

Hive 콘솔이 프로젝트 단위로 발급하는 Client ID입니다. 같은 프로젝트에 속한 모든 App ID가 같은 값을 사용합니다. 값은 보안 키 획득에서 확인하세요.

PKCE: codeChallenge와 codeVerifier

PKCE(codeVerifier·codeChallenge)는 발급되는 인가 코드가 중간에 탈취되어도 악용되지 않도록 보호하는 일회성 값 한 쌍입니다. 앱에서 직접 생성해야 합니다.

Unity

using System;
using System.Security.Cryptography;
using System.Text;

// PKCE(RFC 7636): codeVerifier 생성 + codeChallenge = BASE64URL(SHA256(codeVerifier))
static (string verifier, string challenge) CreatePkce()
{
    var bytes = new byte[32];
    using (var rng = RandomNumberGenerator.Create()) rng.GetBytes(bytes);
    string verifier = Base64Url(bytes);
    using var sha = SHA256.Create();
    string challenge = Base64Url(sha.ComputeHash(Encoding.ASCII.GetBytes(verifier)));
    return (verifier, challenge);
}
static string Base64Url(byte[] b) =>
    Convert.ToBase64String(b).TrimEnd('=').Replace('+', '-').Replace('/', '_');

DeviceKey

DeviceKey는 로그인 세션을 기기 단위로 구분하는 기기 식별 값입니다. Hive Axyl 인증 서버는 이 값을 발급하거나 해석하지 않으므로, 앱에서 직접 만들어 입력해야 합니다.

서버 검증 조건

Hive Axyl 인증 서버는 DeviceKey의 길이와 문자만 검증합니다. 조건을 만족하지 않는 값을 보내면 계정 생성 요청이 실패합니다. 실패 처리는 공통 오류 처리를 참조하세요.

길이: 22자 이상 64자 이하
문자: 공백과 제어 문자를 제외한 ASCII 문자만 허용하며, 한글과 이모지는 허용하지 않음
형식: 검증하지 않음

앱이 지켜야 할 조건

서버는 이 값이 실제로 한 기기에 대응하는지 확인하지 않으므로, 아래 조건은 앱이 직접 지켜야 합니다.

기기마다 서로 다른 값. UUID 같은 난수 권장
기기에 저장해 두고 계속 재사용하는 값

조건을 지키지 않은 경우

호출할 때마다 값을 새로 만들면 서버는 같은 기기를 매번 다른 기기로 인식합니다. 반대로 앱 코드에 고정값을 넣으면 그 앱을 쓰는 모든 사용자의 모든 기기가 같은 값을 보냅니다. 고정값도 위 검증 조건만 만족하면 서버 검증을 통과합니다.

고정값을 넣은 앱에서 한 사용자가 기기 두 대로 로그인하면 서버는 둘을 같은 기기로 봅니다. 나중에 로그인한 기기가 앞선 기기의 로그인 세션을 덮어쓰므로, 사용자는 기기를 번갈아 쓸 때마다 다시 로그인해야 합니다. 한 기기에서 로그아웃하면 다른 기기의 로그인도 함께 끊깁니다. 서버가 오류를 반환하지 않으므로 이 증상은 사용자 문의가 쌓인 뒤에야 드러납니다.

생성 예시

형식은 앱이 정합니다. UUID, 16진수 문자열, base64 등 원하는 체계를 사용할 수 있으며, UUID v4를 권장합니다. 아래 예시는 UUID v4에서 하이픈을 뺀 32자 문자열을 만듭니다.

Unity

using System;

// deviceKey: 최초 실행 시 한 번만 만들고, 만든 값은 기기에 저장해 계속 재사용합니다.
static string NewDeviceKey() => Guid.NewGuid().ToString("N");

Note

여기서 만든 DeviceKey는 이후 같은 게스트 계정으로 다시 로그인할 때도 같은 값을 넣습니다.

2. 게스트 계정 생성

CreateGuestAsync

CreateGuestAsync()를 호출해 게스트 계정을 생성합니다.

호출 파라미터

필드명	타입	필수 여부	설명
request	GuestCreateRequest	Required	게스트 계정 생성 요청
context	ApiCallContext	Optional	호출 단위 설정 객체입니다. 생략하면 기본값이 사용됩니다.

GuestCreateRequest

필드명	타입	필수 여부	설명
`ClientId`	string	Required	프로젝트 단위로 발급되는 콘솔 보안 키의 Client ID
`CodeChallenge`	string	Required	PKCE 코드 챌린지(`codeVerifier`의 SHA256 해시)
`CodeChallengeMethod`	`CodeChallengeMethod`	Required	PKCE 방식. `S256`
`DeviceKey`	string	Required	로그인 세션을 기기 단위로 구분하는 기기 식별 값. 22자 이상 64자 이하
`GrantKey`	string	Optional	앱 서버가 발급받아 전달한 grant key입니다. 추가 보안을 켠 앱에서는 필수입니다. 추가 보안이 꺼져 있어도 보낼 수 있으며, 보낸 값은 설정과 관계없이 항상 검증되고 소비됩니다. 추가 보안 적용을 참조하세요.

호출 예시

요청 수행이 불가능한 공통 실패(Failure)의 결과 모델과 처리 원칙은 공통 오류 처리를 참조하세요.

Unity

using Hive.Axyl.Auth;
using Hive.Axyl.Core;
using UnityEngine;

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

var (codeVerifier, codeChallenge) = CreatePkce();
// 최초 실행에서만 새로 만듭니다. 만든 값은 기기에 저장해 이후 요청에 다시 사용하세요.
string deviceKey = NewDeviceKey();

var result = await auth.CreateGuestAsync(new GuestCreateRequest {
    ClientId            = "{clientId}",
    CodeChallenge       = codeChallenge,
    CodeChallengeMethod = CodeChallengeMethod.S256,
    DeviceKey           = deviceKey,
    // GrantKey: 추가 보안을 켤 때를 대비해 앱 서버가 발급받은 grant key를 넣는 것을 권장합니다.
});

switch (result)
{
    case AuthCreateGuestResult.Success success:
        long   playerId   = success.Data.PlayerId;
        string guestToken = success.Data.GuestToken;
        // playerId·guestToken·deviceKey를 다시 사용하면 같은 게스트 계정으로 로그인할 수 있습니다.
        break;

    // 공통 실패 처리 (네트워크·서버 오류)
    case AuthCreateGuestResult.Failure failure:
        HiveError err = failure.Problem;
        Debug.LogError($"[{err.Code}] {err.Message} (trace: {err.TraceId})");
        break;

    // 안전망: 처리하지 않은 결과 및 알 수 없는 신규 결과(UnknownOutcome)
    default:
        Debug.LogWarning($"처리되지 않은 결과: {result.GetType().Name}");
        break;
}

응답 데이터

성공 시 AuthCreateGuestResult.Success의 Data(GuestCreateResponseData)에 결과가 담깁니다.

필드명	타입	필수 여부	설명
`Data.PlayerId`	long	Required	새로 만든 계정을 식별하는 Player ID
`Data.GuestToken`	string	Required	재로그인에 사용하는 게스트 자격 증명
`Data.AuthorizationCode`	string	Required	액세스 토큰과 리프레시 토큰 발급에 사용하는 인가 코드
`Data.CreatedAt`	DateTimeOffset	Required	생성 시각(UTC)

Data.PlayerId, Data.GuestToken, DeviceKey, ClientId는 다음 게스트 로그인 단계에 필요합니다.

Note

Data.PlayerId, Data.GuestToken, DeviceKey, ClientId는 실제 서비스에서 같은 계정으로 다시 로그인할 때에도 필요합니다. Data.AuthorizationCode는 액세스 토큰과 리프레시 토큰 발급에 사용하는 인가 코드입니다. 하지만 이 코드는 로그인 과정에서 사용하지 않습니다. 로그인에 필요한 인가 코드는 이후 로그인 단계에서 새로 발급받습니다.

응답 예시

Unity

// Success 분기에서 success.Data 예시
// success.Data.PlayerId          = 12345
// success.Data.GuestToken        = "gt_..."
// success.Data.AuthorizationCode = "ac_..."
// success.Data.CreatedAt         = 2026-06-10T00:00:00+00:00   // DateTimeOffset(UTC)

응답 상태

AuthCreateGuestResult의 응답 케이스는 switch 구문으로 처리하는 것을 권장합니다.

응답 케이스	설명	앱 클라이언트 대응
`Success`	게스트 계정 생성 성공. `Data`에 `PlayerId`·`GuestToken` 등이 담깁니다.	계정 생성 결과를 확인한 뒤 로그인 단계를 진행
`InvalidClientId`	Client ID가 올바르지 않은 경우	콘솔 보안 키 확인
`InvalidGrantKey`	`GrantKey`로 보낸 grant key가 유효하지 않거나 만료된 경우	앱 서버에서 grant key를 다시 발급받아 재시도. 추가 보안 적용 참조
`GrantRequiredMissing`	추가 보안(grant key) 설정이 활성화되어 있으나 `GrantKey`가 누락된 경우	추가 보안 적용 설정 확인
`IpBlocked`	접속 IP가 차단된 경우	정책 안내
`ProviderConfigNotFound`	앱에 설정된 로그인 수단(Provider 구성)이 없는 경우	콘솔 로그인 설정 확인
`AppNotFound`	앱 정보를 찾을 수 없는 경우	콘솔의 앱 등록 상태 확인
`TerminateService`	서비스가 종료된 앱인 경우	서비스 운영 상태 확인
`UnknownOutcome`	이 SDK 버전이 알지 못하는 신규 결과	로깅 후 보수적으로 처리
`Failure`	공통 Failure입니다. 필수 파라미터 누락 또는 형식 오류(`invalid_parameter`), 필수 필드 누락(`missing_field`), `X-App-Id` 헤더 누락(`missing_app_id`)도 이 경우에 해당합니다. 원인은 `Failure.Problem.ExternalCode`에 담깁니다. 공통 오류 처리를 참조하세요.	공통 오류 처리 기준에 따라 처리

다음 단계

생성한 계정으로 로그인하려면 로그인을 참조하세요.

Note

계정 생성만으로는 로그인 세션이 만들어지지 않습니다. 로그인 단계에서 로그인 세션을 생성합니다.