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):
/sdk/1.5.0/browser.js/sdk/1.5.0/server.js/sdk/1.5.0/same-origin.js/sdk/1.5.0/aikahub-sdk.js/sdk/1.5.0/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.
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.
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.
| Trust | Who can unlock | XP per achievement | Legendary |
|---|---|---|---|
client | Your game client (browser or desktop) | up to 50 | no |
server | Only your game server, with the game key | up to 250 | yes |
Error codes
Every SDK error is an AikaHubError with code, status and final (true means retrying will not help).
| Code | HTTP | Meaning |
|---|---|---|
invalid_token | 401 | The access token expired or was revoked. The browser client refreshes once by itself. |
invalid_client | 401 | Wrong game key or client_id. Retried, because a key change may be in progress. |
invalid_grant | 400 | The code or refresh token is invalid or was reused. Log in again. |
insufficient_scope | 403 | The member did not grant this scope. |
wrong_game | 403 | The achievement belongs to another game. |
server_key_required | 403 | A server-trust achievement must come from your game server. |
not_linked | 409 | The member unlinked your game. Final: drop it. |
unknown_achievement | 404 | Not defined on the Hub (yet). Retried. |
rate | 429 | Too 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.
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.