Curious about the actual application flow?

Usage Scenarios / Signing In

Authentication (Tokens & Validation)

Understanding

STOVE authentication is the procedure that proves identity so that the game client, game server, and web services can safely use STOVE platform user information. By integrating authentication, you can receive the authentication info of users logged in with a STOVE account—without building your own membership system—and use it for all services that require authentication, such as game entry, API calls, payment, and sanction handling.

Components of Authentication

STOVE authentication operates via two main paths depending on the authenticating party.

Authentication Flow Paths by Platform

The authentication flow path and the tools used differ by the platform the game launches on (Mobile/PC/Web/Server).
Integrate only the areas you need, matching your game's launch form.

Token Types and Roles

STOVE issues three main kinds of tokens, each with a different role and expiry time.

Token Usage Policy

These are usage principles that all environments must follow in common, regardless of token type.

Game Identifiers Summary

The game-identifier terms used in STOVE authentication and APIs are below.
The standard identifier is Game ID (string).

• The member identification number inside the STOVE platform is member_no (numeric).
• Currently integrated games receive guid as the member identifier.

Authentication Add-on Features

These are add-on features the STOVE authentication system provides in addition to basic authentication.

Integration Guide

Platform-specific Prerequisites

Depending on your game's launch form, you only need to do the prerequisites for the platforms you need.

Full Authentication Flow

Even across platforms (Mobile/PC/Web), the order in which authentication proceeds is the same. They all follow the 5 steps below, and only the concrete way to implement each step differs by platform.

Environment Distinction Guide

STOVE provides two environments, Sandbox and Live, to separate the development stage from the operations stage.
Key issuance, domains, and the validation API are all operated separately per environment, so be careful not to mix them.

• Issue client_id, client_secret, and service_id separately per environment.
• If the validation API's game_id differs from the service_id of the API Access Token you hold, a 41002 error occurs. Manage them separately per environment and game.

Development

Mobile

Prerequisites

• The call to Auth.login (Android) / [SGSAuth login] (iOS) / Auth.Login (Unity/Unreal) must be complete. When not logged in, accessToken returns null.
• Don't cache the token on the client; re-fetch it from the SDK each time you use it. Since the SDK auto-renews at 80% of the expiry time, the value fetched from the SDK is always the latest.
• Auto-renewal works only while the app process is running. If the process is terminated in the background, renewal stops, so on returning to the foreground, verify the call result and, if expired, guide the user into the re-login flow.
• Even when you need to pass the token to the game server, don't store it on the server side; pass it along each time a client call occurs.

Development Flow

1. The game client looks up the latest AccessToken via a per-platform API such as Auth.accessToken?.token (Kotlin) / [[SGSAuth accessToken] token] (iOS).
2. If the return value is null, the user is not logged in or has logged out, so guide them into the login flow.
3. If you need to pass the token to the game server, pass the token received from the SDK at call time as-is. Don't store it on the server side; receive it anew with each request.
4. The game server validates the token with the STOVE platform's Game User Access Token validation API, then branches into normal entry, re-login prompt, access block, etc. (See the game-server guide for the validation API)

Auto-renewal proceeds in the following sequence:

Troubleshooting

Sample Code

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

PC (PCSDK)

Prerequisites

• BaseSDK initialization (Base_RestartAppIfNecessaryAsync → Base_InitializeEx) and login completion must come first. Calling before initialization returns BASE_NOT_INITIALIZED (16).
• Pre-allocate a sufficiently large buffer to receive the AccessToken. If the length is insufficient, INVALID_PARAM (5) may be returned.
• The client_id / client_secret / service_id for API Access Token issuance must be held by the game server and must not be exposed to the client.
• Don't cache the token; re-fetch it via the SDK when needed. It can be invalidated at any time by the user's re-login, logout, or session change.

Development Flow

1. The game client calls Base_GetAccessToken(buffer, length) to get the latest User Access Token.
2. Validate the returned result (Result) with IsSuccessful(). (Both C/C++ and C# use result.IsSuccessful())
3. If the token needs to be used on the game server, the client passes it to the game server. Don't store it on the server side; receive and pass it again at call time.
4. The game server calls the STOVE platform's Game User Access Token validation API to perform a secondary validation of the token. This requires the API Access Token in the Authorization header.
5. Branch the follow-up handling—normal entry, re-login prompt, access block, etc.—based on the validation response code.

Troubleshooting

Sample Code

// Assumes Base_RunCallback() is registered to be called in the game loop.
constexpr uint32_t kTokenBufferSize = 4096;
wchar_t accessToken[kTokenBufferSize] = { 0 };

auto result = Stove::PCSDK::Base::Base_GetAccessToken(accessToken, kTokenBufferSize);
if (result.IsSuccessful())
{
    // Send the accessToken string to the game server to perform validation.
}
else
{
    // Implement the failure logic (prompt re-login, user guidance, etc.).
}

Server

Prerequisites

• The game server must hold client_id / client_secret / service_id.
  For the issuance procedure and environment (Live/Sandbox) separation, see 2. Integration Guide → Token Issuance Prerequisites above.
• The structure must receive the Game User Access Token from the client with each request. Don't cache it on the game server.

Development Flow

1. The client passes the Game User Access Token to the game server.
2. The game server checks the remaining validity of the API Access Token it holds. (Based on the expires_in received at issuance)
3. If there's no token or less than 30% remaining, call POST /auth/v5/server_token to issue/renew the API Access Token.
   If 30% or more remains, the same token is returned, so you can use the response's access_token as-is.
4. Call POST /member/v3.0/{game_id}/token/verify to validate the Game User Access Token received from the client.
   Put Bearer {API Access Token} in the Authorization header.
5. Branch based on the response code: normal entry (code == 0), re-login prompt, device-registration prompt, access block, etc.
   Identify the user by the response value.guid (GUID-based games) or value.member_no.

Troubleshooting

These are handling approaches per response code. For the detailed response-code and message spec, see the API & SDK Reference menu.

Sample Code

Examples of calling API Access Token issuance (POST /auth/v5/server_token) and Game User Access Token validation (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) Issue the 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) {
        // See the troubleshooting table (40105, etc.)
        throw new IllegalStateException("Token issue failed: " + issueData.path("code"));
    }
    String apiAccessToken = issueData.path("response_data").path("access_token").asText();

    // 2) Validate the 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");
        // Identify the user by value.path("guid").asLong() or value.path("member_no").asLong()
    } else {
        // See the troubleshooting table (40000 / 40101 / 41002 / 46217, etc.)
    }
}

Frequently Asked Questions