> ## Documentation Index
> Fetch the complete documentation index at: https://doc.playsmart.api.dolly.gg/llms.txt
> Use this file to discover all available pages before exploring further.

# PlaySmart quickstart: your first API call in minutes

> Learn how to register a player, authenticate, and make your first PlaySmart API call in under five minutes with four simple steps.

This guide walks you through the four core operations you'll use in every PlaySmart integration: creating a player account, using the access token, fetching game configuration, and tracking your first analytics event. All examples use `curl` and assume your API base URL is [https://playsmart-gateway-1w8ko864.uc.gateway.dev](https://playsmart-gateway-1w8ko864.uc.gateway.dev).

<Steps>
  <Step title="Register a player">
    Send a `POST` request to `/auth/register` with the player's email address, password, and a unique device identifier. The `deviceId` you provide is stored as the player's `auth_user_id` and is used as the JWT subject claim in all future tokens.

    ```bash theme={null}
    curl -X POST https://playsmart-gateway-1w8ko864.uc.gateway.dev/auth/register \
      -H "Content-Type: application/json" \
      -d '{
        "email": "player@example.com",
        "password": "hunter12345",
        "deviceId": "device-abc-123"
      }'
    ```

    A successful registration returns HTTP `201` with an access token, a refresh token, and the new user record:

    ```json theme={null}
    {
      "data": {
        "access_token": "eyJhbGciOiJIUzI1NiJ9...",
        "refresh_token": "eyJhbGciOiJIUzI1NiJ9...",
        "user": {
          "id": "device-abc-123",
          "email": "player@example.com",
          "pseudo": "",
          "total_games_completed": 0
        }
      }
    }
    ```

    <Note>
      Access tokens expire after **30 days**. Refresh tokens expire after **180 days**. Store both securely on the device and use the refresh token to re-authenticate when the access token expires.
    </Note>
  </Step>

  <Step title="Authenticate subsequent requests">
    Include the `access_token` from registration (or login) as a Bearer token in the `Authorization` header on every protected request:

    ```bash theme={null}
    -H "Authorization: Bearer eyJhbGciOiJIUzI1NiJ9..."
    ```

    If the token is missing or invalid, the API returns `401 UNAUTHORIZED`. If the token's `sub` claim does not match the `user_id` in the request body (on ingest endpoints), the API returns `403 FORBIDDEN`.
  </Step>

  <Step title="Fetch game configuration">
    Retrieve the list of active games from `/v1/games`. This endpoint does not require authentication and returns configuration your client needs to initialize gameplay, including store links, ad settings, and version requirements.

    ```bash theme={null}
    curl https://playsmart-gateway-1w8ko864.uc.gateway.dev/v1/games
    ```

    The response contains an array of game objects under `data`:

    ```json theme={null}
    {
      "data": [
        {
          "game_id": 482910374,
          "name": "Coin Dash",
          "bundle_id": "com.playsmart.coindash",
          "play_store_url": "https://play.google.com/store/apps/details?id=com.playsmart.coindash",
          "thumbnail_url": "https://cdn.example.com/coindash.png",
          "game_mode": "level_based",
          "coins_enabled": true,
          "ads_enabled": true,
          "ios_store_id": "1234567890",
          "version": "2.1.0",
          "maintenance": false,
          "min_version_code": 10,
          "post_game_interstitial_every_n_games": 3
        }
      ]
    }
    ```

    You can filter by bundle ID using the `bundle_id` query parameter: `GET /v1/games?bundle_id=com.playsmart.coindash`.
  </Step>

  <Step title="Track an analytics event">
    Send a batch of events to `/ingest/events`. This endpoint requires a Bearer token. The `user_id` in the request body must match the `sub` claim in your access token.

    ```bash theme={null}
    curl -X POST https://playsmart-gateway-1w8ko864.uc.gateway.dev/ingest/events \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer eyJhbGciOiJIUzI1NiJ9..." \
      -d '{
        "user_id": "device-abc-123",
        "game_id": "com.playsmart.coindash",
        "events": [
          {
            "type": "LevelCompleted",
            "timestamp": "2026-04-22T10:30:00+00:00",
            "customdata": {
              "level": 5,
              "score": 1200
            }
          }
        ]
      }'
    ```

    A successful ingest returns HTTP `202`:

    ```json theme={null}
    {
      "success": true,
      "message": "accepted:1 buffered:1"
    }
    ```

    Valid event `type` values are: `AppOpen`, `LevelCompleted`, `GameEnd`, `AdImpression`, `IAPPurchase`, and `Custom`. For `Custom` events, include a `customEventName` string alongside the `type`.
  </Step>
</Steps>