Account Linking

Account Linking

Account linking is the recommended onboarding flow. Start each player as anonymous. Later, let the player add real credentials. The player can play after one call, and the upgrade keeps all data. The player_id, saves, scores, friends, and current session do not change.

POST /v1/auth/anonymous            play immediately
        │
        ▼  (later, from a settings or "save your progress" screen)
POST /v1/auth/link                 attach email + password    ─┐ either,
POST /v1/auth/link/steam           attach a Steam identity     ─┘ or both

Both link calls use the current session (X-Session-Token) and change the calling player. The session stays valid, so the player does not sign in again on this device.

Link email and password

curl -s -X POST http://localhost:8080/v1/auth/link \
  -H "Authorization: Bearer <api_key>" \
  -H "X-Session-Token: <access_token>" \
  -H "Content-Type: application/json" \
  -d '{"email":"player@example.com","password":"correct-horse-battery-staple"}'

The call returns 202 Accepted and sends a verification code by email. To confirm, send the same email and the code to POST /v1/auth/verify.

After verification, the player can use POST /v1/auth/login on any device. Login returns the same player with all data. The verified email also links the player to their global GG Scale account. If no account exists for that email, GG Scale creates one. Display names (PATCH /v1/profile) and friends need this account. See Player Accounts.

Anonymous, Steam, and custom-token players can link an email. A player who already has an email gets 409.

Link a Steam identity

First, set up Steam sign-in for the Game Project. See Steam Sign-In. Get a ticket from GetAuthTicketForWebApi("ggscale"), then send it:

curl -s -X POST http://localhost:8080/v1/auth/link/steam \
  -H "Authorization: Bearer <api_key>" \
  -H "X-Session-Token: <access_token>" \
  -H "Content-Type: application/json" \
  -d '{"ticket":"14000000048bcd42..."}'

The call returns 204 No Content. The player identity is now the Steam account. After this, each POST /v1/auth/steam sign-in on any device returns this player. If you link the same Steam account again, nothing changes.

Only anonymous players and email players can link Steam. A custom-token identity belongs to your backend, so GG Scale does not replace it.

Which method to offer

• In Steam builds, link Steam on first launch, after the anonymous session exists. The player sees no UI and can use other devices immediately.
• On other platforms, offer email linking from a "save your progress" screen. Players who come from custom tokens also need email linking to get display names and friends.
• You can use both. Email gives the global account (names and friends). Steam gives fast sign-in.

Common errors

Call	Status	Meaning
/v1/auth/link	400	The email is not valid, or the password is not 8 to 72 bytes.
/v1/auth/link	409 player already has sign-in credentials	The calling player has an email already.
/v1/auth/link	409 email already in use by another player	Another player in this Game Project has this email.
/v1/auth/link/steam	409 player identity cannot be replaced	The player is a custom-token player.
/v1/auth/link/steam	409 player is linked to a different steam account	The player has a different Steam identity.
/v1/auth/link/steam	409 steam account already linked to another player	Another player in this Game Project has this Steam account.
/v1/auth/link/steam	409 player identity changed, retry	A different request changed the player at the same time. Try again.

A 409 changes nothing. For Steam ticket errors, see the error table in Steam Sign-In.

Full reference: the /v1/auth/link and /v1/auth/link/steam operations.