Management API overview
GraphQL/HTTP API for Crowded Kingdoms management concerns:
| Area | Examples |
|---|---|
| Identity | Sign-in by email + password, magic link, or social/OIDC; federated identities (myIdentities/linkIdentity), me. |
| Organizations | Members, roles, permissions, org tokens. |
| Apps marketplace | Apps metadata, access tiers, app_user_access grants, purchases. |
| Runtime catalog | runtimePermissions query — keys that can be assigned on tiers (not grid grants). |
| Billing | Wallets, transactions, budgets, quotas, Stripe/PayPal checkouts. |
| Hosting | Publish an app to the shared platform (publishAppToShared) and read its routing fields. Customer-provisioned environments were retired without replacement. |
Runtime game data (chunks, voxels, actors, grids, grid permissions, UDP) lives in the Game API, not here. Studio tools that configure grids must call the app’s game API GraphQL endpoint (gameApiUrl), not the management endpoint.
Authentication
- Sign-in: a user signs in with email + password, a magic link, or a social/OIDC provider, and receives a bearer identity session token (64-character hex). Send
Authorization: Bearer <token>on Management API GraphQL requests. Full flow —register/login,requestLoginLink/completeLoginLink,socialLoginStart/socialLoginComplete, and federated identities — is in Sign in. - Identity session token is management-plane only: it is not valid for the Game API / realtime / UDP. To play, mint a short-lived app-scoped token from it (
mintAppToken, or the browser portal flow); see Portals & app-scoped tokens. - Org tokens: a server credential for your organization's own backend, created in the Management UI (or via GraphQL). What a token may call is its scopes; today the only scopes sign in and manage your org-managed players.
GraphQL endpoint
There is one origin per tier, and the management and game surfaces are two surfaces of it. Base URLs are not per organization: nothing is provisioned for you and no hostname is handed out when a stack is ready, because there is no per-tenant stack.
Production: https://ck.prod.crowdedkingdoms.com/graphql — see Connecting game clients for the full setup; build and test there. Crowded Kingdoms' dev and test environments are internal and refuse outside accounts (TIER_ACCESS_REQUIRED). Discover a tier's origin programmatically from the public platformConfig query (sharedGameApiUrl, sharedGameApiWsUrl) rather than hard-coding it.
Hosting an app
Every app runs on the shared platform. Publish it with publishAppToShared — free under your org's app-slot quota (platformConfig.freeAppsPerOrg, default 3), and metered against the org wallet beyond it — then read the app's routing fields (gameApiUrl, deploymentTarget) before a player joins.
See Shared environment & billing for the model and the free allowances, or the portal guide for the same thing in the Management UI.
The customer-provisioned environment surface — environmentDatacenters, environmentFlavors, environmentQuote, createEnvironment, orgEnvironment, linkAppToEnvironment, redeployEnvironment — was retired without replacement and is not in the published SDL. Every app uses the shared platform (publishAppToShared).
Schema reference
GraphQL schema reference — exhaustive types, queries, and mutations for this API.