Authentication
Access and refresh tokens, the OAuth 2.0 token endpoint, device and browser sign-in, publish tokens, game-server sessions, session tickets and the verification keys.
Every authenticated call sends one bearer token:
Authorization: Bearer <token>Which token you use depends on who is calling:
| Caller | Token | How you get it | Lifetime |
|---|---|---|---|
| A player or developer (launcher, game, scripts) | access token, an EdDSA JWT | POST /v1/oauth/token | 900 s |
| The same, to stay signed in | refresh token, opaque | the same response | 30 days, rotated on every use |
0x publish, CI | publish token 0xpub_... | POST /v1/hosting/tokens | until revoked; hosting routes only |
| Your game server | game-server session gs-... | POST /v1/gameservers/logon | 24 h |
| Your game server, for in-game purchases | server key 0xsk_... (older keys: x1sk_..., still valid) | developer portal (Payments) | until rotated |
Tokens are checked on every request. A token that is missing, expired or revoked gets
401 {"error": "invalid or expired token"}. Calls that need no token, such as the public catalog,
work without the header.
Development tokens
The backend can accept long-lived development tokens for local and test setups. They are off on 0x.limo, so use access tokens there.
#Access tokens
An access token is a compact JWT signed with Ed25519 (alg: EdDSA). The header carries a kid. The
claims are:
{"sub": "76561197960287930", "iat": 1792250000, "exp": 1792250900, "jti": "9f2c4e1a0b7d3c55", "iss": "0x1"}sub is the account's SteamID-style ID, as a decimal string. A token is valid for 900 seconds;
expires_in in the token response says exactly how long. Refresh it before it expires; don't wait
for a 401.
Your own server can verify a token offline with the public keys from GET /v1/keys, or
online by calling GET /v1/me with it.
#The token endpoint
POST /v1/oauth/token is an OAuth 2.0 token endpoint (RFC 6749). It takes a form-encoded or JSON body.
Four grants are supported:
grant_type | Use |
|---|---|
password | username + password: the launcher's sign-in form, or your own scripts with your own account |
refresh_token | refresh_token: a new token pair (the old refresh token stops working) |
authorization_code | code + code_verifier + client_id + redirect_uri: browser sign-in with PKCE |
urn:ietf:params:oauth:grant-type:device_code | device_code + client_id: device sign-in |
A successful grant returns:
{"access_token": "eyJhbGciOiJFZERTQSIs...", "token_type": "Bearer", "expires_in": 900, "refresh_token": "3b8f0c..."}curl -s https://api.0x.limo/v1/oauth/token \
-d grant_type=password -d username=alice -d password="$ZEROX_PASSWORD"const r = await fetch("https://api.0x.limo/v1/oauth/token", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ grant_type: "password", username: "alice", password }),
});
const { access_token, refresh_token, expires_in } = await r.json();Warning
Never ask players for their 0x password inside your game. A game that runs in the launcher, or on a
hosted site, gets the player's identity from the launcher or from @0xlimo/platform. The password grant
is for the launcher and for your own developer scripts.
#Refresh tokens rotate
Each refresh_token grant returns a new refresh token and marks the old one used. If a used
refresh token is presented again, the backend assumes it was stolen and revokes the whole session
(every token descended from the same sign-in):
{"error": "invalid_grant", "error_description": "refresh token reuse; session revoked"}Store only the newest refresh token. If two parts of your program refresh at once, one of them signs the user out.
#Sign out
POST /v1/oauth/revoke with token=<refresh token> (RFC 7009) ends that session. It always
answers 200 {}. Access tokens already issued stay valid until they expire, at most 15 minutes.
#Token endpoint errors
The OAuth routes answer errors in the RFC 6749 form {"error": "<code>", "error_description": "..."} with status 400:
error | When |
|---|---|
invalid_grant | wrong username or password; unknown or expired refresh token; refresh-token reuse; code used, expired or not matching the client, redirect URI or PKCE verifier; account suspended |
unsupported_grant_type | a grant not in the table above |
invalid_client | unknown client_id, or a device code polled by another client |
authorization_pending | device flow: the user hasn't approved yet; poll again |
slow_down | device flow: polled faster than every 5 s |
expired_token | device flow: the device code expired (10 min) or was already redeemed |
access_denied | device flow: the user denied the request |
#Device sign-in
Device sign-in follows RFC 8628. Use it for CLIs, TVs and anything without a good browser. This is how
0x login signs in:
POST /v1/oauth/device_authorization {client_id}returnsdevice_code,user_code,verification_uri(https://api.0x.limo/v1/oauth/device),verification_uri_complete,expires_in(600) andinterval(5).- Show the user the
user_codeand the URL. The user signs in there and approves. A signed-in app can approve for them instead withPOST /v1/oauth/device/approve {user_code, allow}. - Poll
POST /v1/oauth/tokenwithgrant_type=urn:ietf:params:oauth:grant-type:device_code, thedevice_codeand theclient_id, everyintervalseconds, until you get tokens.
curl -s https://api.0x.limo/v1/oauth/device_authorization \
-H 'Content-Type: application/json' -d '{"client_id": "x1-cli"}'
# open verification_uri_complete, approve, then:
curl -s https://api.0x.limo/v1/oauth/token \
-d grant_type=urn:ietf:params:oauth:grant-type:device_code \
-d client_id=x1-cli -d device_code="$DEVICE_CODE"const api = "https://api.0x.limo";
const post = (p, b) => fetch(api + p, { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify(b) }).then(r => r.json());
const d = await post("/v1/oauth/device_authorization", { client_id: "x1-cli" });
console.log(`Open ${d.verification_uri} and enter ${d.user_code}`);
for (;;) {
await new Promise(r => setTimeout(r, d.interval * 1000));
const t = await post("/v1/oauth/token", { grant_type: "urn:ietf:params:oauth:grant-type:device_code", device_code: d.device_code, client_id: "x1-cli" });
if (t.access_token) { console.log("signed in"); break; }
if (t.error !== "authorization_pending" && t.error !== "slow_down") throw new Error(t.error_description);
}#Browser sign-in (authorization code + PKCE)
Native apps use authorization code + PKCE (RFC 7636, RFC 8252):
- Open
GET /v1/oauth/authorize?response_type=code&client_id=...&redirect_uri=...&code_challenge=...&code_challenge_method=S256&state=...in the system browser. OnlyS256is accepted. - The user signs in on that page. The browser is redirected to
redirect_uriwithcodeandstate. A loopback redirect (http://127.0.0.1:<any port>/...) may use any port. - Redeem the code with
grant_type=authorization_code,code,code_verifier,client_idandredirect_uri. Codes are single-use and live for 60 seconds.
OAuth clients
OAuth clients (a client_id with its redirect URIs) are registered by 0x. Today the registered clients
are the launcher and the 0x CLI. You can't register your own client yet. Games get the player's
identity through the launcher instead (@0xlimo/platform).
#Accounts
POST /v1/oauth/signup {username, password, persona_name?}creates an account and returns the same token pair as a sign-in, plussteamid,usernameandpersona_name. A username is 3 to 32 characters ofa-z 0-9 _ - .and starts with a letter or digit. A password has at least 10 characters. One address may create at most 5 accounts a day (429 slow_down). A username that is taken gets409 username_taken.POST /v1/oauth/guestcreates a guest account. It has no username or password and can only be reached with its refresh token. Guests own the free apps but can't review, vote or get world tickets.GET /v1/mereturns the caller'ssteamid,persona_name,level,country,language,mc_nameand pushstreamURL.
curl -s https://api.0x.limo/v1/me -H "Authorization: Bearer $ZEROX_TOKEN"#Publish tokens
0xpub_... tokens let a tool publish hosted sites (and submit listings) without your password. They
are valid on /v1/hosting/* and /v1/listings* only. Tokens minted before the rename to 0x start with x1pub_; they keep working and need no change.
POST /v1/hosting/tokens {name}mints one. It needs an access token: a publish token can't mint more tokens. The token appears once in the response, so store it then.GET /v1/hosting/tokenslists your tokens (never the secret) withlast_used_at;DELETE /v1/hosting/tokens/{id}revokes one.
0x login does all of this for you. See Hosting and versions.
#Game servers
A dedicated server logs on as a game server, not as a player:
curl -s https://api.0x.limo/v1/gameservers/logon \
-H 'Content-Type: application/json' -d '{"appid": 480}'
# -> {"steamid": "...", "session": "gs-3f9a...", "public_ip": 1550214401, "stream": "wss://..."}- Without
token, the server gets an anonymous game-server ID. With a game-server logintoken, it keeps a persistent ID. - Send the
sessionas the bearer token. It lasts 24 hours. - Calls marked game server in the reference take this session:
PUT /v1/gameservers/me(the heartbeat that keeps you in the server browser for 90 s), licence checks (GET /v1/gameservers/license/{steamid}/{appid}), ticket checks and stats writes for players in your app.
#Session tickets
The Steam-style session ticket is how a player proves their identity to your game server:
- The client calls
POST /v1/auth/tickets {appid, identity?}and gets{ticket: <hex>, issued}. Only owners of the app get one (403 no licence for this app). The ticket is an Ed25519-signed blob valid for one hour. - The client sends the ticket to your server.
- Your server calls
POST /v1/auth/verify {ticket, appid, steamid?}with its game-server session and gets{ok, steamid, owner}. Each ticket verifies once online, so a replayed ticket fails. Your server can also verify the signature offline with/v1/keys, but then there is no replay protection.
The same session token gets other short-lived tickets:
| Ticket | Endpoint | For |
|---|---|---|
| Encrypted app ticket | POST /v1/apps/{appid}/encrypted_ticket {data} | your servers decrypt it with .../encrypted_ticket/decrypt (game-server session) |
| Ownership ticket | GET /v1/apps/{appid}/ownership_ticket | signed proof that the caller owns the app |
| World join ticket | POST /v1/worlds/{universe}/ticket | joining a public Minecraft-protocol world (60 s; not for guests) |
| Play ticket | POST /v1/apps/{appid}/play-ticket | proving to a hosted site's front that the caller may play (Payments) |
#Verification keys
GET /v1/keys publishes the current and previous Ed25519 public keys, each with its kid. JWTs,
session tickets and inventory results are all signed with these keys. Cache the response and fetch it
again when you see an unknown kid.
curl -s https://api.0x.limo/v1/keys{"alg": "EdDSA", "kid": "b77eced8e7c06123", "ed25519": "fa2f56f3...",
"keys": [{"alg": "EdDSA", "kid": "b77eced8e7c06123", "ed25519": "fa2f56f3...", "current": true}]}In-game purchase receipts use their own key set: GET /v1/iap/keys.
There is no OpenID Connect discovery document for third-party sign-in on the platform API.
#Push channel auth
wss://api.0x.limo/v1/stream takes the same tokens. Browsers can't set headers on a WebSocket, so they
pass the token as a subprotocol instead. See Push stream.
See the generated reference for every OAuth route.
