토큰 발급하기

유저네임 로그인 메서드는 로그인 세션을 바로 만들지 않습니다. 대신 발급 후 180초 동안만 유효한 authorizationCode를 반환합니다. 이 authorizationCode를 입력값으로 사용해 액세스 토큰과 리프레시 토큰을 발급해야 다음 단계에서 세션을 등록할 수 있습니다.

토큰 발급 요청에는 GrantType, ClientId, AuthorizationCode, CodeVerifier를 사용합니다.

1. 토큰 발급 메서드 호출 파라미터 준비

토큰 발급에 필요한 파라미터를 준비합니다.

GrantType

authorization_code를 사용합니다.

ClientId

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

AuthorizationCode

유저네임 로그인 응답의 AuthorizationCode를 사용합니다. 발급 후 180초가 지나면 만료되므로 로그인 직후 이어서 호출합니다.

CodeVerifier

CodeVerifier에는 유저네임 로그인 메서드 호출 시 보낸 codeChallenge와 짝이 되는 codeVerifier를 넣습니다.

2. 액세스 토큰과 리프레시 토큰 발급

IssueTokenAsync

IssueTokenAsync()를 호출해 authorizationCode로 액세스 토큰과 리프레시 토큰을 발급합니다. 인가 코드로 토큰을 발급할 때는 AuthorizationCodeTokenRequest를 사용합니다.

호출 파라미터

필드명	타입	필수 여부	설명
request	TokenRequest	Required	토큰 발급 요청. 인가 코드를 입력값으로 사용하는 토큰 발급에는 AuthorizationCodeTokenRequest를 사용합니다.
context	ApiCallContext	Optional	호출 단위 설정 객체입니다. 생략하면 기본값이 사용됩니다.

AuthorizationCodeTokenRequest

필드명	타입	필수 여부	설명
GrantType	string	Required	authorization_code 고정
ClientId	string	Required	프로젝트 단위로 발급되는 콘솔 보안 키의 Client ID
AuthorizationCode	string	Required	로그인 응답의 AuthorizationCode
CodeVerifier	string	Required	로그인 호출에 보낸 codeChallenge와 짝이 되는 codeVerifier

호출 예시

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

Unity

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

ITokenService token = HiveCore.Resolve<ITokenService>();

// authorizationCode는 [유저네임 로그인] 응답의 Data.AuthorizationCode,
// codeVerifier는 그 로그인 호출에 쓴 codeChallenge와 짝이 되는 값입니다.
// TokenIssueTokenResult 객체
var issueResult = await token.IssueTokenAsync(new AuthorizationCodeTokenRequest {
    GrantType    = "authorization_code",
    ClientId     = "{clientId}",
    AuthorizationCode = authorizationCode,
    CodeVerifier = codeVerifier,   // 로그인 호출에 보낸 codeChallenge와 짝
});
if (issueResult is not TokenIssueTokenResult.Success issued)
{
    // 토큰 발급 실패 처리 (InvalidGrant, InvalidGrantCodeChallenge 등)
    return;
}

응답 데이터

성공 시 TokenIssueTokenResult.Success의 Data(TokenResponseData)에 토큰이 담깁니다.

필드명	타입	필수 여부	설명
Data.AccessToken	string	Required	인증 메서드 호출에 사용하는 액세스 토큰
Data.RefreshToken	string?	Optional	토큰 갱신에 사용하는 리프레시 토큰. 타입은 nullable이나 authorization_code 방식의 토큰 발급에서는 반환됩니다.
Data.ExpiresIn	long	Required	발급 시점으로부터 액세스 토큰이 만료되기까지 남은 시간(초)입니다. 리프레시 토큰의 만료에는 적용되지 않습니다. 다음 단계인 세션 활성화에서 만료 시각을 계산할 때 사용합니다.

응답 예시

Unity

// TokenIssueTokenResult.Success issued
// issued.Data.AccessToken  = "eyJhbGciOi..."   // 인증 메서드 호출에 사용
// issued.Data.RefreshToken = "def502..."        // 토큰 갱신에 사용(authorization_code 방식의 토큰 발급에서 반환)
// issued.Data.ExpiresIn    = 3600               // 만료까지 남은 시간(초)

응답 상태

TokenIssueTokenResult의 응답 케이스는 switch 구문으로 처리하는 것을 권장합니다. 직접 처리하지 않는 케이스는 default에서 안전하게 처리하는 것을 권장합니다.

응답 케이스	설명	앱 클라이언트 대응
Success	토큰 발급 성공. Data에 토큰이 담깁니다.	다음 단계에서 SetSession으로 세션 등록
InvalidGrant	인가 코드가 유효하지 않은 경우	로그인부터 다시 진행
InvalidGrantExpired	인가 코드가 만료된 경우	로그인부터 다시 진행
InvalidGrantCodeChallenge	codeVerifier가 로그인 때 보낸 codeChallenge와 맞지 않는 경우	PKCE 짝 확인
InvalidGrantRefreshToken	리프레시 토큰이 유효하지 않은 경우. refresh_token 방식의 토큰 발급에서만 발생합니다.	로그인부터 다시 진행
InvalidClient	Client ID가 올바르지 않은 경우	콘솔 보안 키 확인
UnsupportedGrantType	지원하지 않는 GrantType인 경우	"authorization_code" 확인
AppNotFound	앱 정보를 찾을 수 없는 경우	콘솔의 앱 등록 상태 확인
TemporarilyUnavailable	서버가 요청을 일시적으로 처리하지 못한 경우. InvalidGrant처럼 서버가 판정한 다른 응답 케이스와 달리, 같은 요청을 다시 보내면 결과가 달라질 수 있습니다.	바로 다시 보내지 말고 간격을 두고 같은 요청을 다시 시도
UnknownOutcome	이 SDK 버전이 알지 못하는 신규 결과	로깅 후 보수적으로 처리
Failure	공통 Failure입니다. 필수 파라미터 누락 또는 형식 오류(invalid_parameter), 필수 필드 누락(missing_field), X-App-Id 헤더 누락(missing_app_id)도 이 경우에 해당합니다. 원인은 Failure.Problem.ExternalCode에 담깁니다. 공통 오류 처리를 참조하세요.	공통 오류 처리 기준에 따라 처리

다음 단계

• 세션 활성화하기