Curious about the actual application flow?

Usage Scenarios / Registering a Device

Device Registration

Understanding

Device registration is a security feature that allows game access only from mobile devices the user has designated, or restricts access at login by designating/managing specific PCs.

Application Methods

For mobile, you can choose the enforcement level of device registration by per-game policy. The device-registration screen is provided as a platform-common UI.
For PC, it's provided as a platform default feature. (No separate integration work is needed.)

Integration Guide

Prerequisites

Basic Integration Structure

The device-registration feature operates via the platform-common UI provided by the STOVE Mobile SDK. The CP company must implement the areas below.

For the device-registration popup/dialog wording, refer to the examples below.

Development

Mobile SDK

Both showing the device-registration popup and the in-game device-management UI are handled automatically by the Auth/AuthUI modules. The game client only needs to call two entry points (AuthUI.Login, AuthUI.ManageDevices) and handle the follow-up flow based on the user's response in the result callback.

Prerequisites

• Modules: you must apply the Auth and AuthUI modules. For SDK installation, see SDK Download and Installation and Development Environment Setup.
• Precondition: after Auth.Initialize completes, you must be using the AuthUI.Login flow. The device-registration screen is shown automatically inside AuthUI.Login. For the login flow, see the Sign-in Guide.
• Permissions/settings: no separate device permissions are needed. The device-registration policy (required/optional, device_setup_exemption) is set by the technical contact in the SDK Config. (See Integration Guide → Prerequisites above)
• Dependencies: the integrated login UI (AuthUI.Login) + an in-game settings screen (where the device management/registration button is placed)

Development Flow

These are the two entry points the MobileSDK handles automatically. The game only needs to handle when to call each entry point and how to branch on the result.

1. On sign-up/login — shown automatically in AuthUI.Login
   • The game calls AuthUI.Login() (same as the usual login flow)
   • The SDK checks the user's device-registration status and, if needed, shows the device-registration screen automatically
     • Required-setting policy + unregistered user → forced display
     • Optional-setting policy → shown only when an account with a registration history accesses from an unregistered device
   • When the user completes registration, the callback returns result.IsSuccessful → proceed with the usual post-login handling
   • If the user closes the screen without completing registration, the callback returns result.IsCanceled → handle the follow-up flow per game policy
     • Recommended: show a guidance UI, then call AuthUI.Login again (recalling makes the SDK show the device-registration screen again)
     • Logging out is not recommended due to the risk of user churn
2. In-game — call AuthUI.ManageDevices
   • Place a device management / device registration button in an appropriate location such as the in-game settings screen
   • Decide whether to show the button using two values of Auth.AccessToken.User (see the table below)
   • On button click, call AuthUI.ManageDevices() → the SDK shows the device registration/management screen automatically
   • Branch on the callback result using the Auth.AccessToken.User.VerifiedDevice value
     • true: registered device → keep the game running
     • false: unregistered device → follow-up flow per policy, such as moving to the initial screen and re-logging in

Troubleshooting

Sample Code

Examples of call/callback handling for the two entry points AuthUI.Login and AuthUI.ManageDevices. Provided per platform.

1. AuthUI.Login — handling the automatic display of the device-registration screen

AuthUI.Login is the same as the usual login call. Just add a result.IsCanceled branch in the callback to handle the follow-up flow when device registration is incomplete.

public void Login()
{
    AuthUI.Login((Result result, AccessToken accessToken) =>
    {
        if (result.IsSuccessful)
        {
            /** Handle login success ... (omitted) **/
        }
        else if (result.IsCanceled)
        {
            /** Device-registration screen closed (registration incomplete) → handle per game policy **/
            /** Recommended: show a guidance UI, then call Login() again → re-show the device-registration screen **/
        }
        else
        {
            /** Other error handling ... (omitted) **/
        }
    });
}

2. AuthUI.ManageDevices — called on in-game button click

Call it when the "device management/registration" button is clicked on the in-game settings screen, etc. After the call, branch the follow-up flow using the Auth.AccessToken.User.VerifiedDevice value.

public void ManageDevices()
{
    if (Auth.AccessToken == null) return;

    AuthUI.ManageDevices((Result result) =>
    {
        if (Auth.AccessToken.User.VerifiedDevice)
        {
            /** Registered device → keep the game running **/
        }
        else
        {
            /** Unregistered device → prompt device registration (e.g., move to the initial screen and retry login) **/
        }
    });
}

Server

This is the area that calls POST /auth-secure/v1.0/my-device/{game_id}/check to look up whether the user's device is registered and whether secondary authentication methods (secondary email verification, phone possession verification) are registered. Use it for branching in-game benefit grants, checking secondary authentication methods, etc.

Prerequisites

• API Access Token issuance must come first. Use it as Bearer {API Access Token} in the Authorization header. See the Authentication menu → Server guide for the issuance procedure.
• The structure must receive the User Access Token from the client with each request. Don't cache it on the game server.

Development Flow

1. The client passes the User Access Token to the game server.
2. The game server checks the remaining validity of the API Access Token it holds and renews it if needed.
3. Call POST /auth-secure/v1.0/my-device/{game_id}/check.
   • Path: fill {game_id} with the Game ID.
   • Headers: Authorization: Bearer {API Access Token}, caller-id: {service_id}_SERVER, Content-Type: application/json
   • Body: { "access_token": "{User Access Token}" }
4. Branch based on the response code.
   • code == 0 → determine device-registration status with value.device_registered.
     • true: registration complete → normal entry or in-game benefit grant
     • false: unregistered → guide the client's device-registration flow (the Mobile SDK handles it automatically)
   • code != 0 → see the troubleshooting table

Troubleshooting

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

Sample Code

An example of calling device-registration and authentication-info lookup (POST /auth-secure/v1.0/my-device/{game_id}/check).

// 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()) {

    String body = mapper.writeValueAsString(Map.of(
            "access_token", userAccessToken));

    HttpRequest req = HttpRequest.newBuilder(
            URI.create(baseUrl + "/auth-secure/v1.0/my-device/" + serviceId + "/check"))
            .header("Content-Type", "application/json")
            .header("Authorization", "Bearer " + apiAccessToken)
            .header("caller-id", callerId)
            .POST(HttpRequest.BodyPublishers.ofString(body))
            .build();
    HttpResponse<String> res = client.send(req, HttpResponse.BodyHandlers.ofString());
    JsonNode data = mapper.readTree(res.body());
    if (data.path("code").asInt() != 0) {
        // See the troubleshooting table (40000 / 40101 / 40103 / 41002, etc.)
        throw new IllegalStateException("device check failed: " + data.path("code"));
    }
    JsonNode value = data.path("value");
    boolean deviceRegistered = value.path("device_registered").asBoolean();
    if (deviceRegistered) {
        // Device registration complete — normal entry / grant benefits
    } else {
        // Device unregistered — guide the client's device-registration flow
    }
}

Frequently Asked Questions