Authentication overview

This page summarizes how a player signs in to Open Play: which methods exist, which rules they all share, and which page to go to for details. If you are wiring up player sign-in, start here.

Sign-in methods

Which methods to offer players is the game’s choice; for Google to work, it must be configured in the environment (Game settings › Sign-in methods).

Topics after sign-in: Sessions and CSRF, Account linking, Server-side verification.

Which method should I choose?

• If an account is not required, start with guest; as the player progresses, link them to email or Google with guest upgrade. The player ID (playerId) does not change.
• If you want multiple devices, you need email/password or Google; a guest identity depends on the secret the device stores.
• For native mobile sign-in (Apple, Game Center, Play Games), HTTP endpoints exist, but the SDKs have no helper.

Rules that apply to every call

The rules below apply to all endpoints under /v1/auth/*.

1. Environment header. Every request carries x-crx-env: <environment-id>. If it is missing or not a UUID, the response is 401.

2. Content type. Requests with a body are sent with Content-Type: application/json.

3. CSRF. Every request other than GET requires double-submit CSRF protection: the __Secure-crx.csrf cookie and a matching x-csrf-token header. On every successful use the token is returned and changes. You first get a token with GET /v1/auth/csrf. Details: Sessions and CSRF.

4. Origin check. For state-changing requests coming from a browser, the Origin domain must be bound to the environment. See Architecture and hosting.

5. Field names are snake_case. Request and response bodies use snake_case (display_name, bootstrap_token, old_password). Two exceptions: displayName in the GET /v1/auth/session response, and the body/response of POST /v1/auth/session/display-name (displayName). The SDKs hide this difference from you and present camelCase.

6. Error bodies. Errors are mostly plain text (permission denied, rate limited…). The only meaningful error with a JSON body is the 403 {"code":"account_banned","message":"account banned"} response for a banned account. Status codes: 400 invalid input, 401 environment or session missing/invalid, 403 denied (wrong password, CSRF, expired token — the distinction is deliberately not leaked), 409 conflict, 422 unprocessable, 429 rate limit. Details: Errors.

Successful sign-in response

The sign-in, sign-up, refresh, and OAuth callback endpoints return the same envelope and write two cookies (__Secure-crx.session, __Secure-crx.refresh; HttpOnly; Secure; SameSite=Lax; Path=/, Max-Age=15552000 = 180-day upper bound):

{
  "player": {
    "id": "0192…",
    "display_name": "Guest",
    "email": null,
    "email_verified": false,
    "is_guest": true,
    "image": null,
    "created_at": "2026-11-03T10:00:00+00:00"
  },
  "tokens": {
    "session_token": "<64 hex>",
    "refresh_token": "<64 hex>",
    "access_token": "<jwt>",
    "expires_in_secs": 900
  },
  "is_new_player": true
}

Warning

In browser games, do not store the session and refresh tokens in JavaScript; the cookies are HttpOnly, and that is what they are for. The SDKs do not put token bodies in state, logs, or errors.

Rate limits

The auth endpoints are subject to fixed-window rate limits. When exceeded, 429 and the plain text rate limited are returned; there is no Retry-After header: you must wait out the window yourself. Do not resend a failed attempt immediately.

If there is an extra proxy in front of the server and the trusted proxy addresses have not been declared, all players fall into a single IP bucket. See Architecture and hosting.

Endpoint summary

The /v1/auth/organization/* endpoints (player organizations) are being deprecated: they work, but every response carries a Deprecation header and they are not described in this document. The /v1/auth/admin/* endpoints are for player administration with a server key (list, ban, rename, session revocation) and are listed in the endpoint reference.

Banned accounts

When an operator bans a player, all of the player’s sessions are revoked and their open realtime connection closes. How the player appears at sign-in:

• A banned email account with the correct password: 403 and {"code":"account_banned","message":"account banned"}. A wrong password or an unknown address is an indistinguishable plain-text 403; the ban status does not leak.
• A banned guest: if a guest sign-in is made with the same bootstrap secret, or by presenting the banned player’s old session, 403 account_banned is returned again and no new player is created.
• GET /v1/auth/session returns 401 for a banned account (the ban code does not leak); refresh, the OAuth callback, and guest upgrade are rejected indistinguishably for a banned owner.
• The response contains no ban reason or end time.
• SDK behavior: in TypeScript the session state becomes banned; in Unity SessionStatus.Banned. Neither opens a new guest, and neither deletes the stored guest secret (so a banned player cannot escape by opening a new guest). Show the player that the account is suspended; do not build a retry loop.