Skip to content

Logins and tokens

Players never type a username or password into a game built with otomo, yet every one of them has their own account. This page explains how that works, what a token is, and what the SDK does when a login runs out. You don't need to write any of this. The SDK handles it, but it explains messages like 401 and AuthenticationLost.

Why a server needs to know who you are

A server receives requests from thousands of games at once. When one of them says "put me in a party", the server must know who "me" is, and must be sure it isn't someone pretending. Proving who you are is called authentication, usually shortened to auth. Otomo's Auth service does it.

The player's identity: a device ID

The first time your game runs on a computer, the SDK makes up a long random string, the device ID, for example q3JqN1mG4c8u9xYwT0bVn5dKs2LpR7eHf6AzWiUoQyE, and saves it in the game's user data folder. That string is the account. Whenever the game shows it to Auth, Auth answers "ah, that player".

This is called an anonymous or device login: no email, no password, no sign-up screen. It's how many mobile and casual games work.

The device ID is the account

Anyone who copies another player's device ID file becomes that player. The SDK never prints it in logs, and you should never ask players to send it. If a player deletes their user data folder, the SDK makes a new ID, which means a new, empty account. A device-only account cannot be recovered; one with Steam or Google linked can (below).

Other ways to sign in

A player can also sign in with Steam or Google, and link either to the account they already have, so the same progress follows them to another computer. Auth checks the Steam ticket or the Google code with the provider itself; the game never sees a password or a secret. Linking never merges two accounts, and a player can unlink a method as long as one way in remains. More ways to sign in explains it for players and developers; Sign in with Steam, Google and other providers is the setup.

What protects the device ID, and what doesn't

The device ID is a password the player can't change. Otomo limits the damage if one leaks, but it can't undo a leak:

  • The database never holds the device ID. Auth stores a keyed hash of it, written hmac2: followed by 64 hex characters, and the key is a random secret called the pepper that exists only on that deployment. A copy of the database alone can't be turned back into device IDs, and the same player looks unrelated on two deployments.
  • Encryption only covers part of the journey. HTTPS protects the device ID between the game and your server's front door. It doesn't stop someone who already has the file, and it isn't what makes the account safe. Inside your server, the request travels between otomo's services without HTTPS.
  • A copied device ID can't be cancelled yet. Whoever holds it can log in again. The audit trail below shows that it happened; it doesn't prevent it.

Keep the pepper

Losing a deployment's pepper means every player gets a new, empty account at their next login, and it can't be recreated or changed. Back it up with the signing key. deploy/README.md, "The device pepper", has the details.

Tokens: a pass instead of a password

Sending the device ID with every single request would be risky: the more often a secret travels, the more chances it has to leak. So the game shows it once, and Auth hands back a token in exchange.

A token is a piece of text that works like a wristband at a festival: you show your ticket once at the gate, get a wristband, and from then on you just show the wristband. The wristband says who you are, it's hard to fake, and it expires.

Otomo gives the game two tokens:

Token Lasts Used for Kept where
Access token 15 minutes Attached to every request: "this is player X" Only in memory, never saved
Refresh token 30 days Getting a new access token when the old one expires Saved in user://otomo/refresh_token

How the access token travels

The game attaches the access token to each request in a header (see HTTP and APIs):

GET /api/player/session/me HTTP/1.1
Authorization: Bearer eyJhbGciOiJFZERTQSIsImtpZCI6Ij…

"Bearer" means "whoever carries this token is allowed in", which is exactly why tokens must be kept secret.

What's inside a token

The access token is a JWT (JSON Web Token, often pronounced "jot"). It's three pieces of text joined by dots: a header, the claims (the facts it states, such as the player's ID and the expiry time), and a signature.

The signature is the clever part. Auth signs every token with a secret key only it knows. Anyone can check the signature using Auth's public key, but nobody can make a valid one without the secret. So when otomo's other services receive a token, they check it themselves in microseconds, without asking Auth, and they know it's genuine.

What happens when a token expires

Fifteen minutes is short on purpose: if an access token ever leaks, it's useless soon. The SDK handles expiry for you:

  1. The game makes a request with an expired access token.
  2. The server answers 401 Unauthorized.
  3. The SDK sends the refresh token to Auth and gets a new access token and a new refresh token. The old refresh token stops working at that moment.
  4. The SDK saves the new refresh token and repeats the original request, which now works.

Your game code never sees steps 2 to 4. It just gets its answer, slightly later.

Why the refresh token changes every time

Every refresh token works exactly once. If a stolen refresh token is ever used after the real game has already used it, Auth notices the reuse and cancels the whole chain of tokens. The thief is locked out, and the real player simply logs in again with their device ID.

Two copies of a game sharing one saved login can refresh at almost the same moment, and that isn't a theft. So for 30 seconds after a refresh, a second use of the old token is just refused: nothing is cancelled, and that copy of the game logs in again.

When the SDK gives up

If a request still gets 401 after a refresh, the login can't be repaired in the background: for example, the server cancelled the token chain, or the server's signing key changed. The SDK then raises the AuthenticationLost signal. Your game should go back to its start-up screen and log in again (calling StartAsync again does that). See the SDK reference.

Seeing and ending sessions

Each login starts one session: the chain of refresh tokens that login produced. A player can list their own sessions and end them, using their access token:

Request What it does
GET /auth/sessions Lists the player's live sessions, and marks the one making the request
DELETE /auth/sessions/{family_id} Ends one session
DELETE /auth/sessions Ends every session, including this one
POST /auth/logout Ends the session the refresh token belongs to

Ending a session stops its refresh token at once. An access token already handed out keeps working until it expires, up to 15 minutes later. The list shows sessions, not devices: two installs sharing one device ID look the same to Auth, so it can't tell them apart.

Deleting an account

DELETE /auth/account, with the player's access token, erases the login: every session, every way of signing in (the device ID, and any linked Steam or Google account), and the account itself. It can't be undone. If that device, or the same Steam or Google account, signs in again it gets a new account with a new player ID.

This doesn't yet delete what Session holds for that player, such as their profile and friends. That part is planned for a later milestone, and deploy/README.md, "Erasing a player", says what support records until then.

The login audit

Auth writes one row for every login attempt: which account, how it logged in, whether it worked, and when. It stores a keyed hash of the address and the User-Agent, never the values themselves, and never a device ID or a token. Operators use it to answer "did someone else use this account?".

Login rows are kept for 90 days, then removed. The setting is AUTH_LOGIN_EVENT_RETENTION.

401 versus 403

These two codes look similar but mean different things, and mixing them up causes bugs:

Code Means What the SDK does
401 Unauthorized "I don't know who you are": the token is missing, expired or invalid Refreshes once and retries once
403 Forbidden "I know who you are, and you're not allowed to do this" Nothing: a new token wouldn't change the answer

For example, a player who isn't the party leader and tries to launch the match gets 403 with the code not_leader. Refreshing wouldn't make them the leader.

Staff accounts are separate

The people who use the admin website log in differently: with an email, a password and, usually, a second factor from an authenticator app. They get staff tokens from a separate service. A player token is never accepted by the admin side, and a staff token is never accepted by the game side, so even a leaked token can't cross over. See Use the admin website.

Where the SDK keeps things

In the game's user data folder (in Godot: Project → Open User Data Folder), under otomo/:

File What it is Safe to delete?
device_id The player's identity Only if you want a new account
refresh_token The saved login Yes; the game logs in again with the device ID
patch/ Downloaded content (Content and patching) Yes; the game downloads it again

Next

Continue with How otomo fits together, a tour of every otomo service.