> ## Documentation Index
> Fetch the complete documentation index at: https://docs.playstarters.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Launch a Game

> Generate a temporary URL to launch a game for a player.

Generates a temporary, single-use URL that opens the game for a specific player. The URL is short-lived and must be loaded by the client immediately.

## Endpoint

```http theme={null}
POST /operator/launch
```

## Headers

| Header          | Value                                        |
| --------------- | -------------------------------------------- |
| `Authorization` | `ApiKey ps_<your_api_key>`                   |
| `Content-Type`  | `application/json`                           |
| `User-Agent`    | The **end-user's** browser User-Agent string |

<Warning>
  **Always forward the player's real `User-Agent`.**

  PlayStarters uses the `User-Agent` header to detect whether the player is on a mobile or desktop device. Many game providers serve different game builds for mobile and desktop — if the header is missing or incorrect, the player may receive the wrong version.

  If your backend proxies the launch request (i.e. the call to `/operator/launch` is made server-side rather than directly from the browser), you **must** forward the original `User-Agent` header from the player's browser.
</Warning>

## Body parameters

<ParamField body="gameId" type="string" required>
  Game identifier. Accepts a game slug (e.g. `pragmatic:sweet-bonanza`), an internal UUID, or an external provider ID. Retrieve values from [`GET /operator/games`](/api/operator/games).
</ParamField>

<ParamField body="playerId" type="string" required>
  Your unique identifier for the player. This is the same value PlayStarters will send to your Seamless Wallet endpoint as `playerId`.
</ParamField>

<ParamField body="currency" type="string" required>
  ISO 4217 currency code (e.g. `EUR`, `USD`, `BRL`). Must match the wallet currency your backend will return for this player.
</ParamField>

<ParamField body="locale" type="string" default="en">
  ISO 639-1 locale code for the game UI language. Defaults to `en`.
</ParamField>

<ParamField body="returnUrl" type="string">
  URL to redirect the player to when they close the game. If omitted, the request's `Origin` header is used as fallback.
</ParamField>

<ParamField body="depositUrl" type="string">
  URL to your deposit page. Some providers display a deposit button inside the game that links here.
</ParamField>

<ParamField body="demo" type="boolean" default="false">
  Launch in demo/fun mode. No real-money wallet calls will be made.
</ParamField>

<ParamField body="ip" type="string">
  Player's IP address. Forwarded to the game provider for geo-checks and fraud prevention.
</ParamField>

<ParamField body="playerEmail" type="string">
  Player's email address. Some providers require this for regulatory compliance.
</ParamField>

<ParamField body="playerFirstName" type="string">
  Player's first name. Used by providers that display player info in-game.
</ParamField>

<ParamField body="playerLastName" type="string">
  Player's last name.
</ParamField>

<ParamField body="playerNickname" type="string">
  Player's display name or username. Defaults to `playerId` if omitted.
</ParamField>

<ParamField body="playerCountry" type="string">
  ISO 3166-1 alpha-2 country code for the player's country (e.g. `DE`, `BR`). Used by some providers for regulatory compliance.
</ParamField>

<ParamField body="token" type="string">
  Player auth token (JWT). Used by some game providers for player identification. If omitted, `playerId` is used as fallback.
</ParamField>

<ParamField body="sessionPayload" type="string">
  Arbitrary string echoed back in wallet callbacks. Useful for tracking campaign attribution or session metadata.
</ParamField>

## Example request

```bash theme={null}
curl -X POST https://api.playstarters.io/operator/launch \
  -H "Authorization: ApiKey ps_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "User-Agent: <end-user's browser User-Agent>" \
  -d '{
    "gameId": "pragmatic:sweet-bonanza",
    "playerId": "your_unique_user_id",
    "currency": "EUR"
  }'
```

## Response — 200 OK

```json theme={null}
{
  "gameUrl": "https://gs.example.com/launch?token=abc123",
  "scriptUrl": "https://gs.example.com/script.js",
  "externalId": "provider:game_code",
  "provider": "pragmatic",
  "sessionToken": "f2d7b0bb993ddc36aa573b3b0f15bfdf"
}
```

### Response fields

<ResponseField name="gameUrl" type="string">
  Temporary URL that loads the game for the requested player. Open this URL in an iframe or a new browser window/tab on the client.
</ResponseField>

<ResponseField name="scriptUrl" type="string">
  Script that must be included on every page embedding the game (required by some providers).
</ResponseField>

<ResponseField name="externalId" type="string">
  The aggregator's internal game identifier (for debugging).
</ResponseField>

<ResponseField name="provider" type="string">
  The provider code used.
</ResponseField>

<ResponseField name="sessionToken" type="string">
  Opaque session token. If present, you can pass it back to [`POST /operator/close-session`](/api/operator/close-session) when the player leaves the game to clean up the session immediately. **This field is optional** — if omitted, the session expires automatically after a period of inactivity.
</ResponseField>

<Warning>
  Treat the launch URL as a session token. Do not log it, cache it, or share it across players. Each call to `/operator/launch` returns a fresh URL.
</Warning>

<Note>
  Before launching, make sure your [Seamless Wallet callback](/api/wallet/overview) is reachable. PlayStarters will call it as soon as the game opens to read the player balance, and again for each bet, win, or refund.
</Note>