Player linking and consent

Require a compatible native consent build

A compatible ggbucks mobile build that implements the v2 consent screen is required. The previously released app is not assumed ready. Confirm availability before offering end-to-end account linking; the public contract is not a release-readiness guarantee.

The native app owns its inspect/approve endpoints, canonical profile and session-bound device admission. A human explicitly reviews the game account and taps Approve inside ggbucks. Never automate native approval, collect a player Clerk token on a game server, or call it with a developer/game-secret credential.

Create an intent for the authenticated game account

Your trusted game backend sends POST /api/game-sdk/v2/links using its server secret and externalPlayerId derived from its authenticated account. Store the returned player UUID on that server. The token expires after 600 seconds.

The game opens only ggbucks://developer-game-link?linkToken=... for native consent. Keep the short-lived token out of logs, device persistence, analytics and arbitrary callback/redirect parameters.

import { nativeConsentUrl } from './game-server.mjs';
// On the authenticated game server:
const intent = await client.createLinkIntent(authenticatedGameAccount.id);
// Store intent.playerId against that account and return a short-lived handoff.
const url = nativeConsentUrl(intent.linkToken);
// The game client opens this fixed ggbucks URL; the HUMAN approves in ggbucks.
// No player Clerk session or native approve call belongs in the game server.

Poll server status with a stopping condition

Poll GET /api/game-sdk/v2/players/{playerId} from the game backend with its secret key at a bounded interval. Return status only to the authenticated game account that owns that mapping; stop on linked status or intent expiry. The response does not expose canonical ggbucks identity.

Cancel or expired consent keeps ordinary gameplay available. Starting another intentional link requires a fresh intent; never treat opening a URL or holding a server secret as consent.

Use the same contract in your project

Read the focused agent skill or download its source and contract ZIP. Review the included source before adding it to your game. Exact fields and action variants are available in the API reference.