Frequently asked questions

This page gathers the questions that come up most often in integration with short answers. For details, go to the linked pages.

Getting started and topology

Can I put the server key inside the game? No. The server key is only on your server. The game client works with the player session; if you need a key embedded in the client there is a client key, but the endpoints it can call are limited, and on some endpoints there is no key-type gate (security, endpoints).

Why am I getting a CORS error? The server does not send CORS headers to an origin that is not in an environment’s domain list (or the operator’s global allowed list). Add the domain in the panel; the origin must be exactly https://<domain>. If the game is on a different registrable domain than Open Play, the session cookie (SameSite=Lax) is not sent; use a same-origin reverse proxy then. Do not add extra CORS headers to your own proxy (architecture and hosting).

My game is a mobile app or Unity desktop; do the browser restrictions apply? The CORS and same-site rule concerns only the browser. Non-browser clients can use a Bearer session token instead of a cookie; but rules such as the CSRF pair on plugin commands and Origin on the realtime ticket request still apply (calling plugins, protocol). For Unity, see the Unity SDK.

Can I use Open Play’s gRPC interface? It is not supported as a public surface. Game integrations go through REST, WebSocket, and the SDKs.

Which SDKs are there? TypeScript (@ferdiunal/open-play-ts) and Unity (com.openplay.sdk). For modules that have no typed CrxClient, you use raw REST (endpoints). Details are on the TypeScript SDK and Unity SDK pages.

Identity

How does the server verify who a player is? Your game server verifies the access JWT returned at player sign-in offline with the JWKS (server verification). It is not the session token or the cookie.

How long does a session live? It slides for 30 days (one request a day is enough), and the absolute ceiling is 180 days. An open realtime socket does not keep the session alive (security).

What happens to a banned player? On sign-in endpoints, after ownership is proven, they get 403 and account_banned; on other endpoints it looks like 401. On plugin endpoints 403 forbidden (message: account banned) (errors).

Replay safety, version, numbers

When is a new Idempotency-Key generated? For every new operation. The same key is used on retries of the same operation; repeating a command with an uncertain outcome with a new key leads to double application (idempotency).

I got 409. Can I repeat the same request? There are two different 409s: on a version conflict (version conflict) first re-read the state; on an “in progress” (idempotent request in progress) response repeat shortly with the same key.

Why is the balance a big integer? Money is a minor-unit integer; floating point is used nowhere. You compute the display decimals yourself (numbers and encoding).

Why do some numbers come as text? Plugin and realtime int64 fields can exceed the safe range of the JavaScript number; so they are carried as decimal text. The TypeScript SDK turns them into bigint.

Why are percentage fields out of 10000? Basis points: 10000 = 100% (numbers and encoding).

Why is the error body sometimes plain text and sometimes JSON? Core REST returns plain text (a few JSON exceptions), plugin endpoints always return JSON. For the decision, look at the status code and, if present, the code field (errors).

Rate limits

Is there a per-key request limit? No; there is no general quota. Certain operations (sign-in, sign-up, chat, plugin commands, socket connection) have limits. In big bulk jobs, apply your own concurrency limit (rate limits).

Hundreds of guests will be opened at the same time at launch. Will it be a problem? Opening a guest is 30 per minute per IP. If the players are on separate IPs it is not a problem; but if your reverse proxy does not forward the client IP, they all gather in one bucket. Verify IP forwarding and do a load test (production checklist).

Plugins

Can I upload my own plugin? No, not yet. Plugins are trusted code compiled into the server; there is no third-party loading or isolation. Today’s paths: rules, webhooks, and your own server (plugins overview).

The plugin schema changed; will my client break? Plugin schemas are pinned by digest (schemaSha256). If the server changes the schema, the old binding sees a mismatch and you must regenerate it from the current document (bindings).

A plugin call returned 403 forbidden. Why? Mostly the plugin is not enabled in your environment or the grant version does not match the server’s; or a CSRF/Origin rejection. Look at the plugin’s state in the panel (Plugins).

Realtime

What should I do when the socket drops? Get a new ticket, reconnect, and rejoin durable streams with the last cursor; if ResyncRequired arrives, join without a cursor. The TypeScript SDK does this on its own (reconnect).

Why does the socket close every 5 minutes? Because no player activity arrived on a subscription that accepts input, the server does an idle close (4100). Show a “Continue” screen or send a keep-alive input.

Can I use a socket for notifications and chat? Not directly from the browser: /v1/ws and /v1/chat/ws require the x-crx-env header on the upgrade and the browser cannot add it. In the browser, read the inbox with REST and use the REST endpoints for chat (realtime overview).

Webhooks

Can I accept webhooks without a signature? No. Verify every request’s signature over the raw body and deduplicate with X-Crx-Event-Id (security).

Can I resend an event I missed? There is no resend action in the panel; deliveries are only monitored. Make up for it by reading the state of the relevant resource with REST.

Administration

I lost the key; can I get it back? No; the secret value is shown only at creation time. Generate a new key and revoke the old one (security).

What can I do in the panel, and what should I do with the API? The panel is for managing the game (content, store, economy reports, rules, settings). In-game flows are done with the API and the SDK. For the panel screens, see the relevant panel help pages.

There is something I cannot find in the documentation. First look at troubleshooting and the glossary; if you cannot find it, send your question with the status code, path, and time information.