AikaHub.dev Open the Studio

Docs: the AikaHub kit

This is the advanced layer. Here is how a web game talks to AikaHub, in detail. If you use the Studio or a starter game, all of this is already done for you.

Start here

The AikaHub kit (@aikahub/sdk) is a small library with no dependencies. It works in browsers, Cloudflare Workers, Node 18+ and Deno, and has three parts:

  • browser — A browser or desktop game on its own domain: public PKCE client (login, profile, character, achievements).
  • server — Your game server: confidential client with a game key (server-trust achievements, rewards, retry queue).
  • same-origin — A game hosted on aikahub.com: the member’s own session, plus a guest queue.

Current version: @aikahub/sdk 1.5.0

Hosted files (pin the exact version in production; the integrity hashes are in manifest.json):

In production, load the pinned version and let the browser check its integrity with an import map (below). For desktop or packaged games, or where import maps with integrity are not supported, vendor the file: copy it into your build.

Full SDK reference (every function, with examples)

Register your game

Open the Developer console, accept the AikaHub Developer Agreement and create a developer client: you get a client_id at once. While it is in development, only you and up to 5 testers can log in with it. When it works, fill in its Playground page and submit it: we review it, and then anyone can log in.

Desktop games can register a loopback URI (http://127.0.0.1/…): any port is accepted.

Open the Developer console

The terms are public; you can read them before you sign up: Developer Agreement, SDK License, All versions

What you can use

Each feature is a scope: ask only for what your game needs, the player sees every one on the consent page.

profile
nickname, avatar, level, profile colour and profile link
character
the member’s 3D VRM character: file URL, thumbnail and licence flags
achievements
unlock your game’s achievements and read the member’s rewards in your game
save
cloud saves: your game stores up to 4 save slots per member (≤ 64 KB each) and reads only its own SDK reference
scores
leaderboards: your game sends scores to its own leaderboards (only each member's best is kept); the lists are public SDK reference
visits
visits: your game puts out a snapshot of the member's home (≤ 16 KB), reads neighbours and homes, and sends preset gifts SDK reference
presence
presence: your game reports every 45–60 seconds that the member is playing it now (menu / playing / idle — no free text); logged-in members see it on the member's profile, and the member can turn it off. Send it only from the player's own client while they actually play — keeping members “online” from a server (or anything else) behind their back is a policy violation and can get your game's presence scope revoked SDK reference

Achievement trust levels

Anyone can modify client code, so whatever the client unlocks must be cheap. Valuable achievements need your server.

TrustWho can unlockXP per achievementLegendary
clientYour game client (browser or desktop)up to 50no
serverOnly your game server, with the game keyup to 250yes

Error codes

Every SDK error is an AikaHubError with code, status and final (true means retrying will not help).

CodeHTTPMeaning
invalid_token401The access token expired or was revoked. The browser client refreshes once by itself.
invalid_client401Wrong game key or client_id. Retried, because a key change may be in progress.
invalid_grant400The code or refresh token is invalid or was reused. Log in again.
insufficient_scope403The member did not grant this scope.
wrong_game403The achievement belongs to another game.
server_key_required403A server-trust achievement must come from your game server.
not_linked409The member unlinked your game. Final: drop it.
unknown_achievement404Not defined on the Hub (yet). Retried.
rate429Too many requests. Wait (Retry-After), then try again.
state_mismatch—The callback does not belong to a login started in this tab. Start again.
network_error—The Hub did not answer. Retried.

Retry rules

Send server unlocks through the retry queue, so a Hub outage never costs a player an achievement.

  • done 2xx: done.
  • drop 409 not_linked, 403 and 400: final. Drop it, do not retry.
  • retry 401, 404, 429, 5xx and network errors: retry with exponential backoff (2 s up to 6 h, with jitter), honouring Retry-After.

Unlocks are idempotent: a repeat returns new: false and no XP, so at-least-once delivery is safe. The queue key is unlock:<sub>:<id>, so the same unlock is queued only once.

Privacy

  • The sub is pairwise: the same member has a different sub in every game, so games cannot match their data by it.
  • The Hub never shares email addresses or its internal user ids.
  • Members can unlink your game at any time in their settings. After that your server gets 409 not_linked: remove the link on your side too.
  • Never log tokens, the game key, the Authorization header or the sub.

Rules for published games

Published games run on their own address with a strict security policy: no inline scripts, no scripts from other sites, and connections only to the game itself and AikaHub.

Publishing: rules and limits

Brand assets

Put a “Log in with AikaHub” button and an “On AikaHub” badge into your game.

Rules: the button at least 40 px, the badge at least 48 px tall; clear space of at least a quarter of its height around it; don't recolour, distort or write on it.