Apps API

# The URL your game was opened with:
# https://your-address/?app_id=1&user_id=42&ts=1760000000&sign=<hex>

# Godot Web: take the query string from the page URL
var query := JavaScriptBridge.eval("location.search.slice(1)", true)

func api_url(method: String) -> String:
    return "https://api.zloy.net/v1/%s?%s" % [method, query]

// The URL your game was opened with:
// https://your-address/?app_id=1&user_id=42&ts=1760000000&sign=<hex>

// The SDK picks the parameters up on its own
const p = new URLSearchParams(location.search);
console.log('player', p.get('user_id'));

interface Identity {
  app_id: string; user_id: string; ts: string; sign: string;
}

const p = new URLSearchParams(location.search);
const identity: Identity = {
  app_id: p.get('app_id') ?? '',
  user_id: p.get('user_id') ?? '',
  ts: p.get('ts') ?? '',
  sign: p.get('sign') ?? '',
};

# zloy_sdk.gd is an autoload named "Zloy"

func _ready() -> void:
    if await Zloy.login():
        print("hello, ", Zloy.user.nickname)
        # cubes are authorized by the same sign-in:
        var ws := WebSocketPeer.new()
        ws.connect_to_url(await Zloy.cubes_url())
    else:
        # the player declined — play without an account
        pass

# fallback when the browser could not return to the game
func sign_in_by_code() -> void:
    Zloy.device_code_ready.connect(
        func(code, uri): $Label.text = "Enter %s at %s" % [code, uri])
    await Zloy.login_by_code()

# sign out on this device
func sign_out() -> void:
    await Zloy.logout()

// 1. open in the system browser
GET https://zloy.net/oauth/authorize
      ?response_type=code
      &client_id=<app_id>
      &redirect_uri=http://127.0.0.1:<port>/zloy
      &code_challenge=<base64url(sha256(verifier))>
      &code_challenge_method=S256
      &state=<random>

// 2. the browser returns ?code=…&state=… to the loopback address

// 3. exchange the code for tokens
POST https://zloy.net/oauth/token
  grant_type=authorization_code&code=…&code_verifier=…
  &redirect_uri=…&client_id=…
→ {ok, access_token, expires_in, refresh_token,
   user, app_id, slug, api_base, ws_url}

// 4. from now on: API methods with Authorization: Bearer <access_token>,
//    cubes at wss://api.zloy.net/rt/ws?access_token=…

// refreshing access (the old refresh token is revoked)
POST /oauth/token  grant_type=refresh_token&refresh_token=…
// signing out
POST /oauth/revoke token=<refresh_token>

// sign-in by on-screen code
POST /oauth/device  client_id=<app_id>
→ {device_code, user_code, verification_uri, interval}
POST /oauth/token
  grant_type=urn:ietf:params:oauth:grant-type:device_code
  &device_code=…

extends Node

var query := ""

func _ready() -> void:
    query = JavaScriptBridge.eval("location.search.slice(1)", true)
    call_api("getUserInfo", _on_user_info)

func call_api(method: String, cb: Callable) -> void:
    var req := HTTPRequest.new()
    add_child(req)
    req.request_completed.connect(
        func(_result, _code, _headers, body):
            cb.call(JSON.parse_string(body.get_string_from_utf8()))
            req.queue_free())
    req.request("https://api.zloy.net/v1/%s?%s" % [method, query])

func _on_user_info(res: Dictionary) -> void:
    if res.get("ok"):
        print("hello, ", res.user.nickname)

<script src="https://zloy.net/assets/zloy-sdk.js"></script>
<script>
  const me = await zloy.getUserInfo();
  console.log('hello,', me.user.nickname);

  const friends = await zloy.getUserFriends(0, 100);
  console.log(friends.total, friends.friends);
</script>

import 'https://zloy.net/assets/zloy-sdk.js';

interface User {
  user_id: number; username: string; nickname: string; avatar: string;
}
interface Self extends User {
  lang: 'ru' | 'en';   // account language — the player themselves only
}
interface UserInfo { ok: boolean; user: Self }
interface FriendsPage {
  ok: boolean; total: number; offset: number; limit: number; friends: User[];
}

declare const zloy: {
  getUserInfo(): Promise<UserInfo>;
  getUserFriends(offset?: number, limit?: number): Promise<FriendsPage>;
  getUserFriendsInApp(offset?: number, limit?: number): Promise<FriendsPage>;
  getToken(): Promise<{ok: boolean; token: string; expires_in: number}>;
  postResult(text: string): Promise<{ok: boolean; url: string; seq: number}>;
  pay(description: string, amount: number): Promise<{ok: boolean; error?: string}>;
  rt: RealtimeApi;   // server cubes, see /docs/backend
};

const me: UserInfo = await zloy.getUserInfo();

{
  "user_id": 42,
  "username": "zloysega",
  "nickname": "Sergey",
  "avatar": "https://zloy.net/uploads/avatars/u42-abc123.png",
  "lang": "ru"        # getUserInfo only
}

{
  "user_id": 42,
  "username": "zloysega",
  "nickname": "Sergey",
  "avatar": "https://zloy.net/uploads/avatars/u42-abc123.png",
  "lang": "ru"        // getUserInfo only
}

interface User {
  user_id: number;
  username: string;
  nickname: string;
  avatar: string;   // '' when not set
}

interface Self extends User {
  lang: 'ru' | 'en';   // account language; the player themselves only
}

import hmac, hashlib

def valid(app_id, user_id, ts, sign, app_key):
    want = hmac.new(app_key.encode(),
                    f"{app_id}:{user_id}:{ts}".encode(),
                    hashlib.sha256).hexdigest()
    return hmac.compare_digest(want, sign)

import {createHmac, timingSafeEqual} from 'node:crypto';

function valid({app_id, user_id, ts, sign}, appKey) {
  const want = createHmac('sha256', appKey)
    .update(`${app_id}:${user_id}:${ts}`).digest('hex');
  return want.length === sign.length &&
    timingSafeEqual(Buffer.from(want), Buffer.from(sign));
}

func valid(appID, userID, ts int64, sign, appKey string) bool {
    mac := hmac.New(sha256.New, []byte(appKey))
    fmt.Fprintf(mac, "%d:%d:%d", appID, userID, ts)
    want := hex.EncodeToString(mac.Sum(nil))
    return hmac.Equal([]byte(want), []byte(sign))
}

// client: fetch the token and hand it to your own server
const {token} = await zloy.getToken();
socket.send(JSON.stringify({auth: token}));

# pip install pyjwt[crypto] requests
import jwt, requests

jwks = requests.get("https://zloy.net/.well-known/jwks.json").json()
key = jwt.PyJWK.from_dict(jwks["keys"][0]).key
claims = jwt.decode(token, key=key, algorithms=["EdDSA"],
                    issuer="https://zloy.net",
                    audience="your-game-slug")
user_id = int(claims["sub"])

import {createRemoteJWKSet, jwtVerify} from 'jose';

const jwks = createRemoteJWKSet(
  new URL('https://zloy.net/.well-known/jwks.json'));

const {payload} = await jwtVerify(token, jwks, {
  issuer: 'https://zloy.net',
  audience: 'your-game-slug',
});
const userId = Number(payload.sub);

call_api("getUserInfo", func(res):
    if not res.get("ok"):
        match res.get("error"):
            "expired": _ask_reload()
            _:         push_warning("API: %s" % res.error))

const r = await zloy.getUserInfo();
if (!r.ok) {
  if (r.error === 'expired') askReload();
  else console.warn('API:', r.error);
}

type ApiError = 'bad_request' | 'expired' | 'unknown_app'
  | 'bad_sign' | 'unknown_user' | 'posting_locked' | 'rate_limited';

const r = await zloy.getUserInfo();
if (!r.ok) handle((r as {error: ApiError}).error);