Advanced Runtime API

Create an account directly when you are building below the SDK facade.

Most games should start with PersistlyGameSaves. This reference page exists for engine wrappers, custom SDKs, and direct runtime integrations that intentionally manage accountId and accountSessionToken themselves.

Advanced Request

POST /api/v1/accounts

Use a stage or live runtime key in the Authorization header. externalAccountRef is optional and stored as a non-authoritative reference only; do not send provider auth tokens through public runtime requests.

HTTP

POST https://api.persistly.app/api/v1/accounts
Authorization: Bearer ps_test_your_runtime_key
Content-Type: application/json

{
  "playerRef": "player-184",
  "externalAccountRef": {
    "provider": "auth0",
    "subject": "auth0|user_123"
  },
  "accountData": {
    "diamonds": 1200,
    "battlePassTier": "silver",
    "displayName": "Ayla"
  },
  "slot": {
    "slotId": "autosave",
    "slotInfo": {
      "characterName": "Ayla",
      "className": "Mage",
      "level": 5
    },
    "data": {
      "checkpoint": "vault",
      "level": 5,
      "coins": 418
    }
  }
}

Advanced Response

201 Created

Persistly returns the account, first slot, runtime sync policy, and one account session token.

JAVASCRIPT

HTTP/1.1 201 Created
Content-Type: application/json

{
  "accountId": "acc_01HXYZ",
  "accountSessionToken": "pst_01HSESSION",
  "syncPolicy": {
    "minRemoteSyncIntervalSeconds": 60,
    "forceSyncCooldownSeconds": 10,
    "syncOnAppBackground": true,
    "syncOnAppForeground": true,
    "syncOnReconnect": true,
    "maxQueuedLocalSnapshots": 25
  },
  "account": {
    "accountId": "acc_01HXYZ",
    "accountData": {
      "diamonds": 1200,
      "battlePassTier": "silver"
    },
    "slots": [
      {
        "slotId": "autosave",
        "slotInfo": {
          "characterName": "Ayla",
          "className": "Mage",
          "level": 5
        },
        "version": 1,
        "status": "active",
        "updatedAt": "2026-05-04T10:00:00Z"
      }
    ],
    "version": 1
  },
  "slot": {
    "slotId": "autosave",
    "slotInfo": {
      "characterName": "Ayla",
      "className": "Mage",
      "level": 5
    },
    "data": {
      "checkpoint": "vault",
      "level": 5,
      "coins": 418
    },
    "version": 1,
    "status": "active",
    "updatedAt": "2026-05-04T10:00:00Z"
  }
}

Rules

The account response is the only time the session token is returned.

PersistlyGameSaves creates the remote account and slots on first sync, so beginner game code can start with saveData/loadData and grow into named slots when needed.

Anonymous games can use the flow as-is because the facade stores accountId, accountSessionToken, and slot references locally.

Games with their own auth can send a non-secret externalAccountRef such as provider plus subject for bookkeeping, but Persistly does not validate provider tokens in the public runtime API.

accountId is the permanent handle for the player account. The game must persist it locally or in its own backend.

accountSessionToken is required to load the account and create/load/sync account-owned slots.

Each slot is addressed through its stable slotId.

clearLocalAccount is local-only. archiveSlot retires an active slot. deleteSlot and deleteAccount are permanent erasure flows.

playerRef and externalAccountRef are non-authoritative references. They are stored for future trusted flows, not public lookup.

Normal game integrations should use account-scoped slot routes and keep internal save handles behind the SDK/API facade.