Independent Game Backend Authentication API

NBTiktok authenticates the account and signs short-lived JWTs. The game client owns routing. Local, test, and production backends use the same credentials.gameBackend contract, audience, and JWKS verifier.

#Game client flow

Call POST /api/game-client/v2/login with only email, password, gameId, mode, and clientBuild. When independent backend authentication is enabled, the response includes:

• backendAuth: audience, operator, privacy policy, and configuration version; never a URL.
• credentials.gameBackend: an Ed25519 JWT valid for at most 30 minutes.

Read separate HTTP and WebSocket URLs from trusted build configuration. A local build may use NBT_GAME_BACKEND_HTTP_URL=http://127.0.0.1:19101 and NBT_GAME_BACKEND_WS_URL=ws://127.0.0.1:19101/ws. Plaintext is permitted only on localhost, 127.0.0.0/8, or [::1]; remote test and production URLs require HTTPS/WSS. Never upload either URL to NBTiktok, and never follow a cross-origin redirect while carrying the Bearer token.

Verify iss, the exact urn:nbtiktok:game-backend:<gameId> audience, gameId, scope=game.session, space, sub, iat/nbf/exp, maximum lifetime, signature, and kid through /.well-known/game-backend-jwks.json. Use (gameId, space, sub) as the data identity and isolate Sandbox from Production.

The Node SDK is @nbtiktok/game-backend-auth 0.4.x. Use createVerifier; the same configuration works in every backend environment and accepts no Token lifetime longer than 1,800 seconds.

#Independent backend WebSocket

This WebSocket is separate from the platform event endpoint /ws/game-client/v2: the independent backend uses credentials.gameBackend.token, while the platform endpoint continues to use its one-use credentials.websocket.ticket. Never interchange them.

Open the trusted backend URL with the fixed nbt.game-backend.v1 subprotocol. Do not put the Token in the URL, a Cookie, or the subprotocol. Within five seconds of opening, send this text frame, no larger than 20 KiB:

{"type":"nbt.auth","token":"<credentials.gameBackend.token>"}

Pass the exact text to SDK verifyWebSocketAuthFrame(text, verifier, currentClaims?). Success returns the verified Claims and a safe acknowledgement:

{"type":"nbt.auth.ok","expiresAt":"2026-09-02T12:30:00.000Z"}

After platform Session refresh returns a new Backend JWT, send the same nbt.auth frame on the existing connection. Reauthentication requires the same gameId, space, sub, and sid, then atomically updates the account snapshot, configuration version, and expiry. Do not accept business frames before initial authentication or while an ordered reauthentication frame is pending. Close when the installed JWT expires.

Use close code 4401 for missing, invalid, or expired authentication, 4403 for an identity change, 4408 for authentication timeout, 1009 for an oversized frame, and 1013 when JWKS is temporarily unavailable. Redact Authorization headers and token fields. Browser deployments must also enforce an exact Origin allowlist; native clients without Origin still require JWT authentication.

The repository's runnable examples/independent-game-backend service demonstrates HTTP Bearer, first-frame WebSocket authentication, in-place renewal, a browser client, and a Node client on loopback.

#Browser Portal

The third-party site creates state and an S256 PKCE transaction, then opens /game-portal/authorize with response_type=code, client_id, exact redirect_uri, state, code_challenge, code_challenge_method=S256, and prompt=login.

The user re-enters the NBTiktok email and password only on the official NBTiktok page. The callback receives a 60-second, single-use Code and the original state; the backend exchanges it at POST /api/game-portal/v2/token and verifies portalToken with the Portal JWKS.

Production uses the registered HTTPS callback. Local Portal uses only http://127.0.0.1:<port>/__nbt/callback or the IPv6 loopback equivalent. Use createPortalAuthorizationRequest, exchangePortalCode, and createPortalVerifier from the SDK.

After verification, create your own HttpOnly, Secure, SameSite=Lax Cookie. Limit it to eight hours and authorizationExpiresAt. NBTiktok does not proxy application requests or own the third-party Cookie.