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):
"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:
- The game makes a request with an expired access token.
- The server answers
401 Unauthorized. - 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.
- 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.