Skip to main content

Dev tier — connecting game clients

The dev tier is Crowded Kingdoms' shared integration environment for early client work. Sign up, create an app on the shared platform, and connect to the live shared Game API — no VM provisioning or environment slug assignment.

First external handoff

The dev tier is actively evolving. If something fails, report it early with the step, error message, and URL you were using — do not spend long periods debugging alone.

Public dev hosts​

SurfaceURL
Management UI (sign up, create app, wallet)https://app.dev.crowdedkingdoms.com
GraphQL API — management AND game, one endpointhttps://ck.dev.crowdedkingdoms.com/graphql
WebSocket subscriptions — same originwss://ck.dev.crowdedkingdoms.com/graphql
GraphQL playgroundhttps://ck.dev.crowdedkingdoms.com/graphql
There is one endpoint, not two

This table listed a separate "Management API" on api.dev.crowdedkingdoms.com and a "Shared Game API" on a game.shared.dev.* host until 2026-08-21. Neither host serves any more — the first answers 503 and the second refuses the connection — and the two surfaces have been one origin for some time. Do not set managementUrl; it was removed in CrowdyJS 14.

Programmatic discovery (no auth required):

query {
  platformConfig {
    sharedGameApiUrl      # https://ck.dev.crowdedkingdoms.com
    sharedGameApiWsUrl    # wss://ck.dev.crowdedkingdoms.com
    freeAppsPerOrg        # default 3
  }
}

After you create an app, confirm routing:

query {
  app(appId: "<your-app-id>") {
    appId
    deploymentTarget   # "shared"
    runtimeStatus      # "active"
    gameApiUrl
  }
}
Do not use legacy dev-box URLs

There is ONE origin per tier, and on this tier it is ck.dev.crowdedkingdoms.com. Per-developer dev boxes and the old game.shared.* split are retired — those hosts no longer serve.

Prefer what the API hands you over a template. All three tiers are now ck.<tier>.crowdedkingdoms.com — dev moved on 2026-08-25, test on 2026-08-26 and production on 2026-08-27, and production carries a prod. label like the other two, so ck.crowdedkingdoms.com without one is an alias rather than the endpoint. That template has been rewritten twice in a month, and a host copied out of an older page is dead rather than slow.

If an app is pinned to a datacenter, mintAppToken returns gameApiUrl and gameApiWsUrl. Use what the token returns. That is correct on every tier, survives the next move, and is the only form that names the datacenter holding your app.

Two tokens (required)​

One endpoint serves everything, but Crowded Kingdoms separates identity from gameplay by credential:

  1. Identity — sign-in (email + password, magic link, or social/OIDC; there is no dev bypass), org and app operations. Sign-in returns an identity session token, and that token cannot drive gameplay.
  2. Gameplay — chunks, voxels, actors, UDP proxy subscriptions, and world mutations. Needs an app-scoped token minted from the session token (mintAppToken, or the portal PKCE flow), not the login token.

See Client Workflow and Portals & app-scoped tokens.

Flow: sign in → create app (or use existing) → mint an app-scoped token → make gameplay calls with that token, against the URLs the mint returned.

Create your account and app​

You do not need a shared admin account. Sign in with email and a password, a magic link, or a social provider.

  1. Open https://app.dev.crowdedkingdoms.com
  2. Sign in with a magic link (enter your work email; the account is created on first sign-in) or a social provider, then set your gamertag
  3. Create an org if prompted, then run Get started to register your app — see Create your first app
  4. When create completes, runtimeStatus is active and gameApiUrl points at the shared endpoint

Account basics: Account and org basics.

Find your User ID​

To join an existing studio org, share your User ID with an org owner. Find it under Account → Profile (https://app.dev.crowdedkingdoms.com/account) or query me { userId email } in the management GraphQL playground.

Configure your client​

Example after you create your own app (replace appId and email with your values):

ApiHttpUrl=https://ck.dev.crowdedkingdoms.com/graphql
ApiWsUrl=wss://ck.dev.crowdedkingdoms.com/graphql
AppId=<your-app-id>

URL rules:

  • Include /graphql for HTTP; the WebSocket uses the same host with wss://.
  • Prefer mintAppToken return values for gameApiUrl / gameApiWsUrl over hard-coding: an app lives in one datacenter, and those values point at it.

CrowdyJS​

import { createCrowdyClient, BrowserLocalStorageTokenStore } from '@crowdedkingdoms/crowdyjs';

// Identity client — holds the session token (management plane).
const identity = createCrowdyClient({
  httpUrl: 'https://ck.dev.crowdedkingdoms.com/graphql',
  tokenStore: new BrowserLocalStorageTokenStore('crowdyjs:session'),
});

// Sign in. Email + password works on every tier; magic link needs email delivery,
// which the dev tier does not have, and social needs configured provider credentials.
await identity.auth.login({ email: 'you@example.com', password });

// Mint an app-scoped token for your app, then drive gameplay from a per-game client.
const appToken = await identity.portal.mintAppToken('<your-app-id>');

// gameApiUrl / gameApiWsUrl point at the datacenter holding this app.
const game = createCrowdyClient({
  httpUrl: appToken.gameApiUrl ?? 'https://ck.dev.crowdedkingdoms.com/graphql',
  wsUrl: appToken.gameApiWsUrl ?? 'wss://ck.dev.crowdedkingdoms.com/graphql',
  tokenStore: new BrowserLocalStorageTokenStore('crowdyjs:app:<your-app-id>'),
});
game.setToken(appToken.token);

Full SDK guide: CrowdyJS. Routing details: Shared environment routing.

Unreal and other native clients​

Use the same endpoint and the same token model: sign in for the identity session token, mint an app-scoped token for your app, then use that token for gameplay. Browsers typically use the GraphQL UDP proxy; native clients can use the Replication API, signing UDP packets with the app-scoped token after server assignment. Unreal SDK docs: Unreal SDK intro.

Org membership​

Create your own org through Get started, or join an existing studio:

  • Org owners invite members by User ID — see Account and org basics.
  • Dev accounts are separate per tier — a test or prod account does not carry over.

Verify connectivity (smoke checklist)​

Goal for dev integration: platformConfig → sign in → create app → mint app token → gameplay.

  1. platformConfig.sharedGameApiUrl returns a URL on the GraphQL playground.
  2. Sign in → create shared app → confirm app.runtimeStatus === "active" and gameApiUrl set.
  3. mintAppToken → receive the app-scoped token and the app's datacenter URLs.
  4. gameClientBootstrap(appId) against those URLs (Bearer = app token) → 200.
  5. connectUdpProxy → connected: true.
  6. sendActorUpdate / sendClientEvent → notifications (not UNAUTHORIZED).

Browser path: GraphQL UDP proxy. Connection overview: Connecting to your app.

If gameplay fails, confirm you are sending an app-scoped token for this app (the identity session token is rejected) and that it has not expired — rotate it with refreshAppToken (or re-mint) on a TOKEN_EXPIRED error.

GraphQL playground​

The API exposes an interactive GraphQL playground at its /graphql path: https://ck.dev.crowdedkingdoms.com/graphql.

Use it for sign-in (login/register, or requestLoginLink/completeLoginLink), me, createApp and mintAppToken, and for gameplay queries — for those, pass Authorization: Bearer <app-scoped token> from mintAppToken (the identity session token is rejected for gameplay). Gameplay for an app placed in another datacenter must be run against that app's own gameApiUrl.