QSPlaySDK.user
Data about the current portal player, the authentication prompt, and a subscription to sign-in/sign-out. For how a game is expected to use accounts, see Requirements · Accounts, Progress & Multiplayer.
Current player
user.getUser() returns the current player's data. A guest and a signed-out user are
indistinguishable to the game — both cases return null.
const user = await QSPlaySDK.user.getUser();
// signed in: { qsid: "YM4YAL", name: "Alex", avatarUrl: "https://..." }
// guest / not signed in: null
Returns SdkUser | null:
interface SdkUser {
qsid: string;
name: string;
avatarUrl: string | null;
}
| Field | Description |
|---|---|
qsid | The player's public identifier on the portal. Not a secret — it can be used for display (for example, in the game's own leaderboard), but not to verify authenticity — for that, see the token for the game backend. |
name | The player's display name. |
avatarUrl | A link to the player's avatar, or null if no avatar is set. |
Call this method again after the authChanged event rather than
caching the result for long — the player can sign in or out without leaving the game.
Authentication prompt
user.showAuthPrompt() shows the player the portal's sign-in screen without leaving the game page.
await QSPlaySDK.user.showAuthPrompt();
Use it when the game needs a signed-in player (for example, to record a score in a leaderboard) and
getUser() has just returned null. After a successful sign-in the
authChanged event fires — continue the flow on that, not on the result
of showAuthPrompt() itself, which only opens the sign-in screen and doesn't report how it ended.
Authentication listener
user.addAuthListener(callback) subscribes to sign-in/sign-out of the portal account without
leaving the game (for example, the player opened the portal's login screen in a neighbouring tab and
signed in there).
const unsubscribe = QSPlaySDK.user.addAuthListener(({ user }) => {
// user: SdkUser | null
});
// later, if you need to unsubscribe:
unsubscribe();
Event payload (portal → game):
interface AuthChangedEventPayload {
user: SdkUser | null;
}
Subscribe to this event once at game start and use it to reset the token/profile you have cached
and, if necessary, to repeat getUserToken().
Token for the game backend
user.getUserToken() returns a short-lived token for the game's server, so that the game's backend
can confirm the player's identity to the portal when recording a result (for example, in a
leaderboard), without trusting qsid from getUser() alone (it isn't a secret — it is also visible
in other public places on the portal).
const token = await QSPlaySDK.user.getUserToken();
// send the token to your backend; the backend presents it to the portal
Returns a string — the token itself. Its lifetime isn't exposed: the SDK keeps it internally and
silently refreshes the token about 30 seconds before it expires — repeated getUserToken() calls
within that window return the cached value without a new request to the portal.
If nobody is signed in, the promise rejects with an SdkError,
error.code === "USER_NOT_AUTHENTICATED" (the full list of codes is on the Errors
page):
try {
const token = await QSPlaySDK.user.getUserToken();
} catch (error) {
if (error.code === "USER_NOT_AUTHENTICATED") {
await QSPlaySDK.user.showAuthPrompt();
// request the token again after the authChanged event
}
}
Token format and backend verification
The token is an RS256-signed JWT bound to this particular game, not to the portal as a whole.
Inside is the same qsid as in user.getUser().qsid (not the portal's internal numeric id — that
is never exposed externally), so the token can be checked against what the game has already
received from the client via getUser(). An example of the decoded payload:
{ "qsid": "YM4YAL", "game_code": "brain-blast", "iat": 1727520000, "exp": 1727523600 }
| Field | Description |
|---|---|
qsid | The player's public identifier — matches user.getUser().qsid. |
game_code | The code of the game the token was issued for — check it against the expected one if your backend serves several games. |
iat | The time the token was issued, unix time in seconds. |
exp | The time the token expires, unix time in seconds. Lives for about an hour. |
The public key for verifying the signature (RS256, PEM) is served at a short address:
https://play.quartsoft.com/publicKey.json
Fetch it once and cache it on your side (if signature verification fails, it's worth re-fetching in case the key was rotated) — the signature is verified locally on your server, without calling the portal on every request:
import jwt from "jsonwebtoken";
const { publicKey } = await fetch("https://play.quartsoft.com/publicKey.json").then((r) => r.json());
const { qsid, game_code } = jwt.verify(token, publicKey, { algorithms: ["RS256"] });
Don't decode or trust the token on the client — verifying the signature only makes sense on your server, which has grounds not to trust the client.