실제 적용 흐름이 궁금하신가요?

이용 시나리오 / 로그인하기

인증(토큰·검증)

이해하기

스토브 인증은 게임 클라이언트·게임 서버·웹 서비스가 스토브 플랫폼의 이용자 정보를 안전하게 활용할 수 있도록 신원을 증명하는 절차예요. 인증을 연동하면 자체 회원 시스템을 구축하지 않고도 스토브 계정으로 로그인한 이용자의 인증 정보를 받아 게임 진입, API 호출, 결제, 제재 처리 등 인증이 필요한 모든 서비스에 활용할 수 있어요.

인증의 구성 요소

스토브 인증은 인증 주체에 따라 크게 두 가지 경로로 동작해요.

플랫폼별 인증 동선

게임이 출시되는 플랫폼(Mobile/PC/Web/Server)에 따라 인증 동선과 사용하는 도구가 달라요.
자사 게임의 출시 형태에 맞춰 필요한 영역만 연동하면 돼요.

토큰의 종류와 역할

스토브에서 발급되는 토큰은 크게 세 가지로, 역할과 만료 시간이 각각 달라요.

토큰 사용 정책

토큰의 종류와 무관하게 모든 환경에서 공통으로 지켜야 하는 사용 원칙이에요.

게임 식별자 정리

스토브 인증·API에서 사용하는 게임 식별자 용어는 아래와 같아요.
식별자는 Game ID(문자열) 를 표준으로 사용해요.

• 스토브 플랫폼 내부의 회원 식별 번호는 member_no(숫자형)예요.
• 현재 연동 게임은 회원 식별자로 guid를 전달받아요.

인증 부가 기능

기본 인증 외에 스토브 인증 시스템이 제공하는 부가 기능이에요.

연동 가이드

플랫폼별 사전 준비

자사 게임의 출시 형태에 따라 필요한 플랫폼의 사전 준비만 진행하면 돼요.

전체 인증 흐름

플랫폼(Mobile/PC/Web)이 달라도 인증이 진행되는 순서는 동일해요. 모두 아래 5단계를 따르며, 각 단계를 구현하는 구체적인 방법만 플랫폼에 따라 달라요.

환경 구분 안내

스토브는 개발 단계와 운영 단계를 분리하기 위해 Sandbox와 Live 두 환경을 제공해요.
키 발급·도메인·검증 API 모두 환경별로 별도 운영되므로 혼용하지 않도록 주의해요.

• 환경별로 client_id·client_secret·service_id를 별도 발급받아요.
• 검증 API의 game_id와 보유한 API Access Token의 service_id가 다르면 41002 오류가 발생해요. 환경·게임별로 분리 관리하세요.

개발하기

모바일

사전 준비

• Auth.login(Android) / [SGSAuth login](iOS) / Auth.Login(Unity·Unreal) 호출이 완료된 상태여야 해요. 미로그인 상태에서는 accessToken이 null을 반환해요.
• 토큰을 클라이언트에 캐싱하지 말고 사용 시점마다 SDK에서 재조회하세요. SDK는 만료시간의 80%에 도달하면 자동 갱신을 수행하므로, 매번 SDK에서 가져온 값이 항상 최신이에요.
• 자동 갱신은 앱 프로세스가 실행 중일 때만 동작해요. 백그라운드에서 프로세스가 종료된 상태에서는 갱신이 멈추므로, 포그라운드 복귀 시점에는 호출 결과를 검증하고 만료된 경우 재로그인 흐름으로 유도하세요.
• 게임 서버에 토큰을 넘겨야 하는 경우에도 서버 측에 저장하지 말고, 클라이언트 호출이 발생할 때마다 함께 전달하세요.

개발 흐름

1. 게임 클라이언트가 Auth.accessToken?.token(Kotlin) / [[SGSAuth accessToken] token](iOS) 등 플랫폼별 API로 최신 AccessToken을 조회해요.
2. 반환값이 null이면 미로그인 또는 로그아웃 상태이므로 로그인 흐름으로 유도해요.
3. 게임 서버에 토큰을 전달해야 하면 호출 시점에 SDK에서 받은 토큰을 그대로 전달해요. 서버 측에는 저장하지 말고 매 요청마다 새로 전달받으세요.
4. 게임 서버는 스토브 플랫폼의 Game User Access Token 유효성 검증 API로 토큰을 검증한 뒤 정상 진입·재로그인 유도·접근 차단 등을 분기해요. (검증 API는 게임 서버 가이드 참고)

자동 갱신 동작은 다음 시퀀스로 진행돼요:

트러블슈팅

샘플 코드

public void GetToken()
{
    string token = Auth.AccessToken.Token;
}

PC (PCSDK)

사전 준비

• BaseSDK 초기화(Base_RestartAppIfNecessaryAsync → Base_InitializeEx)와 로그인 완료가 선행돼 있어야 해요. 초기화 전에 호출하면 BASE_NOT_INITIALIZED(16)가 반환돼요.
• AccessToken 수신용 버퍼는 충분한 크기로 미리 할당해야 해요. 길이가 부족하면 INVALID_PARAM(5)이 반환될 수 있어요.
• API Access Token 발급용 client_id / client_secret / service_id는 게임 서버가 보유해야 하며 클라이언트에 노출하지 않아요.
• 토큰은 캐싱하지 말고 필요 시점마다 SDK로 재조회해요. 이용자의 재로그인·로그아웃·세션 변경으로 언제든 무효화될 수 있어요.

개발 흐름

1. 게임 클라이언트는 Base_GetAccessToken(buffer, length)을 호출해 최신 User Access Token을 가져와요.
2. 반환된 결과(Result)를 IsSuccessful()로 검증해요. (C/C++·C# 모두 result.IsSuccessful())
3. 게임 서버에서 토큰을 사용해야 하면 클라이언트가 토큰을 게임 서버로 전달해요. 서버 측에 저장해 두지 않고 호출 시점에 다시 받아 전달해요.
4. 게임 서버는 스토브 플랫폼의 Game User Access Token 유효성 검증 API를 호출해 토큰을 2차 검증해요. 이때 API Access Token이 Authorization 헤더에 필요해요.
5. 검증 결과 응답 코드에 따라 정상 진입·재로그인 유도·접근 차단 등 후속 처리를 분기해요.

트러블슈팅

샘플 코드

// 게임 루프에서 Base_RunCallback() 호출이 등록돼 있다고 가정합니다.
constexpr uint32_t kTokenBufferSize = 4096;
wchar_t accessToken[kTokenBufferSize] = { 0 };

auto result = Stove::PCSDK::Base::Base_GetAccessToken(accessToken, kTokenBufferSize);
if (result.IsSuccessful())
{
    // accessToken 문자열을 게임 서버로 전송하여 유효성 검증을 수행하세요.
}
else
{
    // 실패 시 로직(재로그인 유도, 사용자 안내 등)을 구현해 주세요.
}

Server

사전 준비

• 게임 서버가 client_id / client_secret / service_id를 보유하고 있어야 해요.
  발급 절차와 환경(Live/Sandbox) 분리는 위 2. 연동 가이드 → 토큰 발급 사전 준비를 참고하세요.
• 클라이언트로부터 Game User Access Token을 요청 시점마다 전달받는 구조여야 해요. 게임 서버에 캐싱하지 않아요.

개발 흐름

1. 클라이언트가 게임 서버에 Game User Access Token을 전달해요.
2. 게임 서버는 보유 중인 API Access Token의 잔여 유효기간을 확인해요. (발급 시 받은 expires_in 기준)
3. 토큰이 없거나 잔여 30% 미만이면 POST /auth/v5/server_token을 호출해 API Access Token을 발급·갱신해요.
   30% 이상 남아 있다면 동일한 토큰이 반환되므로, 응답의 access_token을 그대로 사용해도 돼요.
4. POST /member/v3.0/{game_id}/token/verify를 호출해 클라이언트로부터 받은 Game User Access Token의 유효성을 검증해요.
   Authorization 헤더에는 Bearer {API Access Token}을 넣어요.
5. 응답 code에 따라 정상 진입(code == 0), 재로그인 유도, 기기 등록 유도, 접근 차단 등으로 분기해요.
   응답 value.guid(GUID 기반 게임) 또는 value.member_no로 이용자를 식별해요.

트러블슈팅

응답 code 별 처리 방안이에요. 상세 응답 코드·메시지 스펙은 API & SDK 레퍼런스 메뉴를 참고하세요.

샘플 코드

API Access Token 발급(POST /auth/v5/server_token)과 Game User Access Token 유효성 검증(POST /member/v3.0/{game_id}/token/verify) 호출 예제예요.

// Java 25 LTS — java.net.http.HttpClient + Jackson(ObjectMapper)
import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;
import java.util.Map;

ObjectMapper mapper = new ObjectMapper();
String baseUrl = "https://api.onstove.com";
String serviceId = "STOVE_GAME";
String callerId = serviceId + "_SERVER";

try (HttpClient client = HttpClient.newBuilder()
        .connectTimeout(Duration.ofSeconds(5))
        .build()) {

    // 1) API Access Token 발급
    String issueBody = mapper.writeValueAsString(Map.of(
            "client_id", "com.stove.stovegame.clientid",
            "client_secret", clientSecret,
            "service_id", serviceId,
            "instance_id", "server001"));

    HttpRequest issueReq = HttpRequest.newBuilder(URI.create(baseUrl + "/auth/v5/server_token"))
            .header("Content-Type", "application/json")
            .header("caller-id", callerId)
            .POST(HttpRequest.BodyPublishers.ofString(issueBody))
            .build();
    HttpResponse<String> issueRes = client.send(issueReq, HttpResponse.BodyHandlers.ofString());
    JsonNode issueData = mapper.readTree(issueRes.body());
    if (issueData.path("code").asInt() != 0) {
        // 트러블슈팅 표 참고 (40105 등)
        throw new IllegalStateException("Token issue failed: " + issueData.path("code"));
    }
    String apiAccessToken = issueData.path("response_data").path("access_token").asText();

    // 2) Game User Access Token 유효성 검증
    String verifyBody = mapper.writeValueAsString(Map.of(
            "access_token", gameUserAccessToken));

    HttpRequest verifyReq = HttpRequest.newBuilder(
            URI.create(baseUrl + "/member/v3.0/" + serviceId + "/token/verify"))
            .header("Content-Type", "application/json")
            .header("Authorization", "Bearer " + apiAccessToken)
            .header("caller-id", callerId)
            .POST(HttpRequest.BodyPublishers.ofString(verifyBody))
            .build();
    HttpResponse<String> verifyRes = client.send(verifyReq, HttpResponse.BodyHandlers.ofString());
    JsonNode verifyData = mapper.readTree(verifyRes.body());
    if (verifyData.path("code").asInt() == 0) {
        JsonNode value = verifyData.path("value");
        // value.path("guid").asLong() 또는 value.path("member_no").asLong() 로 사용자 식별
    } else {
        // 트러블슈팅 표 참고 (40000 / 40101 / 41002 / 46217 등)
    }
}

자주 묻는 질문