Skip to content

User Accounts 👤

The User Accounts feature allows games to prompt the user to log in, access logged-in user information and authentication tokens. This enables personalized experiences and secure communication between games and Poki User Accounts.

User Interface

The User Accounts module provides three main methods:

  •  ðŸ’¬ login() : Prompts the user to log in if they haven’t already
  •  ðŸ‘¤ getUser() : Returns information about the currently logged-in user
  •  ðŸŽ« getToken() : Returns a game specific JWT authentication token for the current user

User Data Structure

When a user is logged in, the getUser() method returns a User object with the following properties:

interface User {
  username: string;
  avatarUrl: string;
}

SDK Methods

Login

login(): Promise<void>

Prompts the user to log in if they are not already authenticated. If the user is already logged in, this method resolves immediately. Only call this in response to a user interaction that requires an account, avoid calling it automatically on game load.

  • If the user successfully logs in, a full page refresh will occur
  • If the user closes the authentication panel or takes too long (45 seconds), the promise will be rejected
try {
  await PokiSDK.login();
  // The page will reload if the user logs in.
  // In case the user is already logged in, the promise resolves instantly and you can continue from here.
  const user = await PokiSDK.getUser();
  console.log("User logged in:", user.username);
} catch (error) {
  console.log("Login failed:", error.message);
  // User closed auth panel or login timed out
}

Get User

getUser(): Promise<User | null>

Returns the current logged-in user information, or null if no user is logged in. Throws an exception if user accounts is not enabled or if the user has opted out of the feature.

Call this function after your game loads to handle all possible user states (logged in, logged out, or after a page refresh due to an authentication state change). This allows you to provide the appropriate user experience from the start.

try {
  const user = await PokiSDK.getUser();
  if (user) {
    console.log(`Welcome ${user.username}!`);
  } else {
    // User is not logged in, you can call PokiSDK.login() to prompt it
    console.log("User not logged in");
  }
} catch (error) {
  // user accounts is not available or user opted out of the feature
}

Debug Mode (Inspector)

When running with debug mode enabled, getUser() returns static mock data for local development and testing: 

{
  username: 'TestUser',
  avatarUrl: 'https://a.poki-cdn.com/img/placeholder_gradient.png'
}

Get Token

getToken(): Promise<string | null>

Returns a JWT token for the current user, or null if no user is logged in. Throws an exception if user accounts is not enabled or if the user has opted out of the feature. This token can then be verified from your backend.

Important: The token expires in 1 minute for security purposes. Do not store this token or use it for anything other than verifying with the Poki endpoint to obtain the persistent user_id. Generate a new token each time you need to verify a user.

Token Generation

try {
  const token = await PokiSDK.getToken();
  if (token) {
    // Send the token to your backend and verify it to obtain the user_id
    fetch("/your/backend/service", ...);
  } else {
    console.log("No authentication token available");
  }
} catch (error) {
  // user accounts is not available or user opted out of the feature
}

Token Verification

You can verify the token from your backend using the Poki verification endpoint:

// Backend verification example
async function verifyPokiToken(token, teamApiKey) {
  const response = await fetch(
    "https://user-vault.poki.com/auth/verify-token",
    {
      method: "GET",
      headers: {
        Authorization: `Bearer ${token}`,
        "X-Poki-Team-Api-Key": teamApiKey,
      },
    },
  );

  if (response.ok) {
    const verificationResult = await response.json();
    console.log("Token is valid:", verificationResult); // { user_id: "unique-user-identifier" }
    return verificationResult.user_id;
  } else {
    console.log("Token verification failed");
    return null;
  }
}

The verification endpoint returns a user_id that is immutable and unique per game. This user_id should be used as the primary identifier for that user in your backend systems.

Note: You’ll need to obtain your X-Poki-Team-Api-Key from your account manager to use the verification endpoint.

Debug Mode (Inspector)

When running with debug mode enabled, getToken() returns a valid, long-lasting JWT token that works with the Poki verification endpoint. When decoded, this token resolves to the user_id: "debug-user-id". This allows you to test the full authentication flow, including backend token verification.

Cloud Gamesaves

When a user is logged in, the Poki SDK automatically syncs their game saves to the cloud. This is completely transparent — no extra SDK calls or setup are required. Saves are tied to the logged-in user and restored across sessions and devices.

How it works

Every time a user plays a game, the SDK attempts to load their gamesave from the cloud and inject it into the game before it starts. During gameplay, the SDK monitors two browser storage APIs for changes, localStorage and IndexedDB, and batches any updates to sync them back to the cloud at a throttled interval to avoid excessive network activity and bandwidth usage.

Storage limit

1MB Gamesave Limit

The gamesave payload must not exceed 1MB after gzip compression. If a player’s save exceeds this limit, cloud gamesaves will be automatically disabled for that player and their progress will no longer be synced. Design your save data to stay well within this limit.