Skip to main content

Connecting to your app

After you create an app on the shared platform, connection details come from the app dashboard and from Management API queries — not from a dedicated environment detail page. Use those values in game clients, dedicated servers, and CI.

Dev tier (shared integration hosts)​

For early client integration on the dev tier, use the public shared hosts documented in Dev tier (client integration):

SurfaceURL
Management UIhttps://app.dev.crowdedkingdoms.com
Management APIhttps://api.dev.crowdedkingdoms.com
Shared Game API (HTTP)https://game.shared.dev.cks-env.com/graphql
Shared Game API (WebSocket)wss://game.shared.dev.cks-env.com/graphql

Management hosts are shared across the dev tier; all shared-platform apps on dev use the same Game API host, scoped by appId. Each API also exposes a GraphQL playground at /graphql for manual testing.

On test and production tiers, read platformConfig.sharedGameApiUrl or your app's gameApiUrl for the correct host — do not assume the dev URL.

Find your endpoints​

From the app dashboard​

  1. Sign in and open your org: /orgs/:orgSlug.
  2. Open Apps and select your app (/orgs/:orgSlug/apps/:appSlug).
  3. Copy Game API HTTP and WebSocket URLs from the connection section (they match the tier's shared endpoint).

From the Management API​

Public tier defaults (no auth):

query {
  platformConfig {
    sharedGameApiUrl
    sharedGameApiWsUrl
  }
}

Per-app routing (requires org access):

query {
  app(appId: "<your-app-id>") {
    gameApiUrl
    deploymentTarget
    runtimeStatus
  }
}

mintAppToken also returns gameApiUrl and gameApiWsUrl — convenient when wiring clients right after sign-in.

Connection URLs on app dashboard
Screenshot note

This screenshot shows the legacy environment detail layout. On the shared-only portal, the same URL fields appear on the app dashboard.

Connection URLs​

URLUsed for
Management APILogin and identity; returns the identity session token (gameplay tokens are minted separately — see Portals & app-scoped tokens)
Game API (HTTP GraphQL)Browser and server clients using the Game API
Game API (WebSocket)Real-time GraphQL subscriptions (same /graphql path with wss://)
Replication / BuddyUDP replication when enabled for your tier; see Replication API

Do not commit live tokens or secrets to source control.

Configure game clients​

  • Browser games: CrowdyJS talks to the shared Game API GraphQL endpoint. Use mintAppToken (or shared environment routing) for URLs and the app-scoped token.
  • Dedicated servers / buddies: Use Replication API documentation with Buddy endpoints returned by the Game API after assignment.
  • Custom engines: Call Game API GraphQL directly; authenticate with an app-scoped token for the app — mint one with mintAppToken from your identity session token (or the PKCE portal flow). The session token and org/service tokens are management-plane only and are rejected by the Game API. See Portals & app-scoped tokens.

The Management UI does not configure in-world data (grids, actors, chunks). That happens through the Game API after clients can reach the shared endpoint with a valid app token.

Org API tokens (automation)​

For server-side scripts (CI, custom studio backends):

  1. Open /orgs/:orgSlug and select the Tokens tab.
  2. Create an org API token with the permissions you need.
  3. Call Management API GraphQL with the token (same operations you can run in the UI when permitted).

See Account and org basics and the Management API GraphQL reference for createApp, mintAppToken, and related types.

Keep tokens secret; rotation and least-privilege labels are your responsibility.

Verify connectivity​

  1. Confirm app.runtimeStatus is active (query app or appRuntimeState — see Shared environment & billing).
  2. Sign in on the management API for the identity session token.
  3. mintAppToken(appId) → app-scoped token and game URLs.
  4. Call the shared Game API playground or run { __typename } with Authorization: Bearer <app-scoped token>.
  5. For realtime: connectUdpProxy → connected: true; then actor updates or subscriptions (see Dev tier → Verify connectivity).

If runtimeStatus is not active, check wallet balance, spend caps, or subscription state before debugging client code.