0xDocs 0x.limo

Docs / REST API

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:

http
Authorization: Bearer <token>

Which token you use depends on who is calling:

CallerTokenHow you get itLifetime
A player or developer (launcher, game, scripts)access token, an EdDSA JWTPOST /v1/oauth/token900 s
The same, to stay signed inrefresh token, opaquethe same response30 days, rotated on every use
0x publish, CIpublish token 0xpub_...POST /v1/hosting/tokensuntil revoked; hosting routes only
Your game servergame-server session gs-...POST /v1/gameservers/logon24 h
Your game server, for in-game purchasesserver 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:

json
{"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_typeUse
passwordusername + password: the launcher's sign-in form, or your own scripts with your own account
refresh_tokenrefresh_token: a new token pair (the old refresh token stops working)
authorization_codecode + code_verifier + client_id + redirect_uri: browser sign-in with PKCE
urn:ietf:params:oauth:grant-type:device_codedevice_code + client_id: device sign-in

A successful grant returns:

json
{"access_token": "eyJhbGciOiJFZERTQSIs...", "token_type": "Bearer", "expires_in": 900, "refresh_token": "3b8f0c..."}
bash
curl -s https://api.0x.limo/v1/oauth/token \
  -d grant_type=password -d username=alice -d password="$ZEROX_PASSWORD"

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):

json
{"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:

errorWhen
invalid_grantwrong 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_typea grant not in the table above
invalid_clientunknown client_id, or a device code polled by another client
authorization_pendingdevice flow: the user hasn't approved yet; poll again
slow_downdevice flow: polled faster than every 5 s
expired_tokendevice flow: the device code expired (10 min) or was already redeemed
access_denieddevice 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:

  1. POST /v1/oauth/device_authorization {client_id} returns device_code, user_code, verification_uri (https://api.0x.limo/v1/oauth/device), verification_uri_complete, expires_in (600) and interval (5).
  2. Show the user the user_code and the URL. The user signs in there and approves. A signed-in app can approve for them instead with POST /v1/oauth/device/approve {user_code, allow}.
  3. Poll POST /v1/oauth/token with grant_type=urn:ietf:params:oauth:grant-type:device_code, the device_code and the client_id, every interval seconds, until you get tokens.
bash
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"

#Browser sign-in (authorization code + PKCE)

Native apps use authorization code + PKCE (RFC 7636, RFC 8252):

  1. Open GET /v1/oauth/authorize?response_type=code&client_id=...&redirect_uri=...&code_challenge=...&code_challenge_method=S256&state=... in the system browser. Only S256 is accepted.
  2. The user signs in on that page. The browser is redirected to redirect_uri with code and state. A loopback redirect (http://127.0.0.1:<any port>/...) may use any port.
  3. Redeem the code with grant_type=authorization_code, code, code_verifier, client_id and redirect_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, plus steamid, username and persona_name. A username is 3 to 32 characters of a-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 gets 409 username_taken.
  • POST /v1/oauth/guest creates 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/me returns the caller's steamid, persona_name, level, country, language, mc_name and push stream URL.
bashtested
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/tokens lists your tokens (never the secret) with last_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:

bash
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 login token, it keeps a persistent ID.
  • Send the session as 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:

  1. 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.
  2. The client sends the ticket to your server.
  3. 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:

TicketEndpointFor
Encrypted app ticketPOST /v1/apps/{appid}/encrypted_ticket {data}your servers decrypt it with .../encrypted_ticket/decrypt (game-server session)
Ownership ticketGET /v1/apps/{appid}/ownership_ticketsigned proof that the caller owns the app
World join ticketPOST /v1/worlds/{universe}/ticketjoining a public Minecraft-protocol world (60 s; not for guests)
Play ticketPOST /v1/apps/{appid}/play-ticketproving 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.

bashtested
curl -s https://api.0x.limo/v1/keys
json
{"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.