Authentication and Players

Authentication and Players

Authentication turns a player into a session your game can act for. A player belongs to one project. The same person can also carry a global account that links their identity across your games.

Auth methods

Every auth call needs the API key and lives under /v1/auth. None of them need a session token; they return one.

• Anonymous. POST /v1/auth/anonymous with no body. Good for a first launch, before a player commits to a real account.
• Email and password. POST /v1/auth/signup then POST /v1/auth/login. Signup returns 202 and sends a verification email; confirm it with POST /v1/auth/verify.
• Custom token. POST /v1/auth/custom-token exchanges a token your own backend signed for a ggscale session. Use it to bridge an existing account system.

A successful sign-in returns an access_token (the session token), a refresh_token, and the player_id.

Sessions and refresh

The access_token is a short-lived JWT. Send it as X-Session-Token on player calls. When it expires, call POST /v1/auth/refresh with the refresh token to get a fresh pair. POST /v1/auth/logout revokes a refresh token.

Example

# 1. get a session
curl -s -X POST http://localhost:8080/v1/auth/anonymous \
  -H "Authorization: Bearer <api_key>"

# 2. use the returned access_token on a player call
curl -s http://localhost:8080/v1/profile \
  -H "Authorization: Bearer <api_key>" \
  -H "X-Session-Token: <access_token>"

Common errors

• 401 on a player call means the session token is missing, expired, or invalid. Refresh it or sign in again.
• 401 on an auth call means the API key is wrong for this project.

Global account linking

A player can link identities so one person keeps a stable id across several of your games. The link and unlink calls live under /v1/account.

Full reference: the /v1/auth/* and /v1/account/* operations.