接口检索

14 个核心操作已定义；其他接口只提供目录。详细参数、路径／请求头约束和错误响应以下载的 OpenAPI 为准。

按方法、路径、中文说明搜索

GET 读取游戏启动配置

/v1/public/games/{gameSlug}/bootstrap

无请求体。gameId 来自此响应；gameAppId 从后台取得。公开缓存 60 秒，允许 stale-while-revalidate=300。

认证：匿名 · 幂等键：不要求 · 成功：HTTP 200

无请求体

响应

BootstrapResponse · 完整字段定义

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "gameId": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
    },
    "gameSlug": {
      "type": "string",
      "minLength": 2,
      "maxLength": 64,
      "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$"
    },
    "environment": {
      "type": "string"
    },
    "bundleVersion": {
      "type": "string"
    },
    "minimumClientVersion": {
      "type": "string"
    },
    "maintenance": {
      "type": "object",
      "properties": {
        "enabled": {
          "type": "boolean"
        },
        "message": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        }
      },
      "required": [
        "enabled",
        "message"
      ]
    },
    "configVersion": {
      "type": "string"
    },
    "resourceManifestId": {
      "anyOf": [
        {
          "type": "string",
          "format": "uuid",
          "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
        },
        {
          "type": "null"
        }
      ]
    },
    "serverTime": {
      "type": "string",
      "format": "date-time",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
    }
  },
  "required": [
    "gameId",
    "gameSlug",
    "environment",
    "bundleVersion",
    "minimumClientVersion",
    "maintenance",
    "configVersion",
    "resourceManifestId",
    "serverTime"
  ]
}

JSON 示例（人工数据，不能直接登录）

{
  "gameId": "a7000000-0000-4000-8000-000000000001",
  "gameSlug": "sample-game",
  "environment": "development",
  "bundleVersion": "1",
  "minimumClientVersion": "1.0.0",
  "maintenance": {
    "enabled": false,
    "message": null
  },
  "configVersion": "1",
  "resourceManifestId": null,
  "serverTime": "2026-08-30T00:00:00.000Z"
}

GET 读取已发布配置版本

/v1/public/games/{gameSlug}/config/{version}

version 使用 bootstrap.configVersion。响应为游戏自定义 JSON 值（对象、数组或基本值）；缓存一年、immutable，ETag 为 bodyHash。未实现条件 GET/304。

认证：匿名 · 幂等键：不要求 · 成功：HTTP 200

无请求体

响应

GameConfigResponse · 完整字段定义

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "anyOf": [
    {
      "type": "string"
    },
    {
      "type": "number"
    },
    {
      "type": "boolean"
    },
    {
      "type": "null"
    },
    {
      "type": "array",
      "items": {
        "$ref": "#"
      }
    },
    {
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {
        "$ref": "#"
      }
    }
  ]
}

JSON 示例（人工数据，不能直接登录）

{
  "difficulty": "normal"
}

POST 签发设备挑战

/v1/auth/device-challenges

挑战一次性使用，每次登录／刷新发送前重新申请。clientAppId 是后台 gameAppId。429 时指数退避并加抖动；不要轮换 installationId 绕过限流。

认证：匿名 · 幂等键：不要求 · 成功：HTTP 201

请求

DeviceProofChallengeRequest · 完整字段定义

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "operation": {
      "type": "string",
      "enum": [
        "game_login",
        "game_refresh",
        "merge_preflight"
      ]
    },
    "installationId": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
    },
    "platform": {
      "type": "string",
      "enum": [
        "ios",
        "android"
      ]
    },
    "clientAppId": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
    },
    "devicePublicJwk": {
      "type": "object",
      "properties": {
        "kty": {
          "type": "string",
          "const": "EC"
        },
        "crv": {
          "type": "string",
          "const": "P-256"
        },
        "x": {
          "type": "string",
          "pattern": "^[A-Za-z0-9_-]{43}$"
        },
        "y": {
          "type": "string",
          "pattern": "^[A-Za-z0-9_-]{43}$"
        },
        "alg": {
          "default": "ES256",
          "type": "string",
          "const": "ES256"
        },
        "ext": {
          "default": true,
          "type": "boolean",
          "const": true
        }
      },
      "required": [
        "kty",
        "crv",
        "x",
        "y"
      ]
    },
    "deviceKeyId": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
    }
  },
  "required": [
    "operation",
    "installationId",
    "platform",
    "devicePublicJwk"
  ]
}

JSON 示例（人工数据，不能直接登录）

{
  "operation": "game_login",
  "installationId": "a7000000-0000-4000-8000-000000000001",
  "platform": "ios",
  "clientAppId": "a7000000-0000-4000-8000-000000000001",
  "devicePublicJwk": {
    "kty": "EC",
    "crv": "P-256",
    "x": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
    "y": "BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB",
    "alg": "ES256",
    "ext": true
  }
}

响应

DeviceProofChallengeResponse · 完整字段定义

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "challengeId": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
    },
    "nonce": {
      "type": "string"
    },
    "expiresAt": {
      "type": "string",
      "format": "date-time",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
    }
  },
  "required": [
    "challengeId",
    "nonce",
    "expiresAt"
  ]
}

JSON 示例（人工数据，不能直接登录）

{
  "challengeId": "a7000000-0000-4000-8000-000000000001",
  "nonce": "nnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnn",
  "expiresAt": "2026-08-30T00:00:00.000Z"
}

POST Game Center 登录

/v1/auth/game-center

平台 Game Center 签名不是 Sign in with Apple。重试保留 Idempotency-Key、authRequestId 和全部语义字段，重新申请设备挑战并签名。详见快速开始的设备签名和重试协议。

认证：匿名 · 幂等键：必填 · 成功：HTTP 200

请求

GameCenterLoginRequest · 完整字段定义

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "gameSlug": {
      "type": "string",
      "minLength": 2,
      "maxLength": 64,
      "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$"
    },
    "publicKeyUrl": {
      "type": "string",
      "format": "uri"
    },
    "signature": {
      "type": "string",
      "minLength": 1
    },
    "salt": {
      "type": "string",
      "minLength": 1
    },
    "timestamp": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "teamPlayerId": {
      "type": "string",
      "minLength": 1
    },
    "gamePlayerId": {
      "type": "string"
    },
    "bundleId": {
      "type": "string",
      "minLength": 1
    },
    "installationId": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
    },
    "devicePublicJwk": {
      "type": "object",
      "properties": {
        "kty": {
          "type": "string",
          "const": "EC"
        },
        "crv": {
          "type": "string",
          "const": "P-256"
        },
        "x": {
          "type": "string",
          "pattern": "^[A-Za-z0-9_-]{43}$"
        },
        "y": {
          "type": "string",
          "pattern": "^[A-Za-z0-9_-]{43}$"
        },
        "alg": {
          "default": "ES256",
          "type": "string",
          "const": "ES256"
        },
        "ext": {
          "default": true,
          "type": "boolean",
          "const": true
        }
      },
      "required": [
        "kty",
        "crv",
        "x",
        "y"
      ]
    },
    "deviceChallengeId": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
    },
    "deviceChallengeNonce": {
      "type": "string",
      "minLength": 32,
      "maxLength": 128
    },
    "deviceProof": {
      "type": "string",
      "minLength": 80,
      "maxLength": 256
    },
    "authRequestId": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
    }
  },
  "required": [
    "gameSlug",
    "publicKeyUrl",
    "signature",
    "salt",
    "timestamp",
    "teamPlayerId",
    "bundleId",
    "installationId",
    "devicePublicJwk",
    "deviceChallengeId",
    "deviceChallengeNonce",
    "deviceProof",
    "authRequestId"
  ]
}

JSON 示例（人工数据，不能直接登录）

{
  "installationId": "a7000000-0000-4000-8000-000000000001",
  "devicePublicJwk": {
    "kty": "EC",
    "crv": "P-256",
    "x": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
    "y": "BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB",
    "alg": "ES256",
    "ext": true
  },
  "deviceChallengeId": "a7000000-0000-4000-8000-000000000001",
  "deviceChallengeNonce": "nnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnn",
  "deviceProof": "ssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssss",
  "gameSlug": "sample-game",
  "publicKeyUrl": "https://static.gc.apple.com/synthetic.cer",
  "signature": "synthetic-signature",
  "salt": "synthetic-salt",
  "timestamp": 1788048000000,
  "teamPlayerId": "synthetic-player",
  "bundleId": "app.apemotion.sample",
  "authRequestId": "a7000000-0000-4000-8000-000000000001"
}

响应

SessionResponse · 完整字段定义

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "accessToken": {
      "type": "string",
      "minLength": 1
    },
    "refreshToken": {
      "type": "string",
      "minLength": 1
    },
    "expiresAt": {
      "type": "string",
      "format": "date-time",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
    },
    "gameAccountId": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
    },
    "gameId": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
    },
    "originAccountLifecycleId": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
    },
    "deviceKeyId": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
    },
    "created": {
      "type": "boolean"
    }
  },
  "required": [
    "accessToken",
    "refreshToken",
    "expiresAt",
    "gameAccountId",
    "gameId",
    "originAccountLifecycleId",
    "deviceKeyId",
    "created"
  ]
}

JSON 示例（人工数据，不能直接登录）

{
  "accessToken": "synthetic-access-token",
  "refreshToken": "rrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrr",
  "expiresAt": "2026-08-30T00:00:00.000Z",
  "gameAccountId": "a7000000-0000-4000-8000-000000000001",
  "gameId": "a7000000-0000-4000-8000-000000000001",
  "originAccountLifecycleId": "a7000000-0000-4000-8000-000000000001",
  "deviceKeyId": "a7000000-0000-4000-8000-000000000001",
  "created": false
}

POST Play Games 登录

/v1/auth/play-games

serverAuthCode 来自 Play Games 的 server/Web OAuth 客户端。不可放入 OAuth secret。EXTERNAL_IDENTITY_PROOF_REISSUE_REQUIRED 时重新取得平台证明，并新建登录尝试。

认证：匿名 · 幂等键：必填 · 成功：HTTP 200

请求

PlayGamesLoginRequest · 完整字段定义

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "gameSlug": {
      "type": "string",
      "minLength": 2,
      "maxLength": 64,
      "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$"
    },
    "serverAuthCode": {
      "type": "string",
      "minLength": 1
    },
    "recallSessionId": {
      "type": "string",
      "minLength": 1
    },
    "packageName": {
      "type": "string",
      "minLength": 1
    },
    "installationId": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
    },
    "devicePublicJwk": {
      "type": "object",
      "properties": {
        "kty": {
          "type": "string",
          "const": "EC"
        },
        "crv": {
          "type": "string",
          "const": "P-256"
        },
        "x": {
          "type": "string",
          "pattern": "^[A-Za-z0-9_-]{43}$"
        },
        "y": {
          "type": "string",
          "pattern": "^[A-Za-z0-9_-]{43}$"
        },
        "alg": {
          "default": "ES256",
          "type": "string",
          "const": "ES256"
        },
        "ext": {
          "default": true,
          "type": "boolean",
          "const": true
        }
      },
      "required": [
        "kty",
        "crv",
        "x",
        "y"
      ]
    },
    "deviceChallengeId": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
    },
    "deviceChallengeNonce": {
      "type": "string",
      "minLength": 32,
      "maxLength": 128
    },
    "deviceProof": {
      "type": "string",
      "minLength": 80,
      "maxLength": 256
    },
    "authRequestId": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
    }
  },
  "required": [
    "gameSlug",
    "serverAuthCode",
    "packageName",
    "installationId",
    "devicePublicJwk",
    "deviceChallengeId",
    "deviceChallengeNonce",
    "deviceProof",
    "authRequestId"
  ]
}

JSON 示例（人工数据，不能直接登录）

{
  "installationId": "a7000000-0000-4000-8000-000000000001",
  "devicePublicJwk": {
    "kty": "EC",
    "crv": "P-256",
    "x": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
    "y": "BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB",
    "alg": "ES256",
    "ext": true
  },
  "deviceChallengeId": "a7000000-0000-4000-8000-000000000001",
  "deviceChallengeNonce": "nnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnn",
  "deviceProof": "ssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssss",
  "gameSlug": "sample-game",
  "serverAuthCode": "synthetic-auth-code",
  "packageName": "app.apemotion.sample",
  "authRequestId": "a7000000-0000-4000-8000-000000000001"
}

响应

SessionResponse · 完整字段定义

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "accessToken": {
      "type": "string",
      "minLength": 1
    },
    "refreshToken": {
      "type": "string",
      "minLength": 1
    },
    "expiresAt": {
      "type": "string",
      "format": "date-time",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
    },
    "gameAccountId": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
    },
    "gameId": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
    },
    "originAccountLifecycleId": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
    },
    "deviceKeyId": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
    },
    "created": {
      "type": "boolean"
    }
  },
  "required": [
    "accessToken",
    "refreshToken",
    "expiresAt",
    "gameAccountId",
    "gameId",
    "originAccountLifecycleId",
    "deviceKeyId",
    "created"
  ]
}

JSON 示例（人工数据，不能直接登录）

{
  "accessToken": "synthetic-access-token",
  "refreshToken": "rrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrr",
  "expiresAt": "2026-08-30T00:00:00.000Z",
  "gameAccountId": "a7000000-0000-4000-8000-000000000001",
  "gameId": "a7000000-0000-4000-8000-000000000001",
  "originAccountLifecycleId": "a7000000-0000-4000-8000-000000000001",
  "deviceKeyId": "a7000000-0000-4000-8000-000000000001",
  "created": false
}

POST 轮换并恢复会话

/v1/auth/refresh

不需要 Bearer 或 Idempotency-Key。以 refreshRequestId 去重；同一旧 refreshToken 的网络重试必须沿用该 ID 和语义字段，只更新设备挑战。不同 ID 重用旧 token 会撤销会话家族。串行 single-flight 刷新；成功后原子持久化后继 token。

认证：匿名 · 幂等键：不要求 · 成功：HTTP 200

请求

RefreshRequest · 完整字段定义

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "refreshToken": {
      "type": "string",
      "minLength": 32,
      "maxLength": 512
    },
    "installationId": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
    },
    "platform": {
      "type": "string",
      "enum": [
        "ios",
        "android"
      ]
    },
    "deviceKeyId": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
    },
    "devicePublicJwk": {
      "type": "object",
      "properties": {
        "kty": {
          "type": "string",
          "const": "EC"
        },
        "crv": {
          "type": "string",
          "const": "P-256"
        },
        "x": {
          "type": "string",
          "pattern": "^[A-Za-z0-9_-]{43}$"
        },
        "y": {
          "type": "string",
          "pattern": "^[A-Za-z0-9_-]{43}$"
        },
        "alg": {
          "default": "ES256",
          "type": "string",
          "const": "ES256"
        },
        "ext": {
          "default": true,
          "type": "boolean",
          "const": true
        }
      },
      "required": [
        "kty",
        "crv",
        "x",
        "y"
      ]
    },
    "deviceChallengeId": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
    },
    "deviceChallengeNonce": {
      "type": "string",
      "minLength": 32,
      "maxLength": 128
    },
    "deviceProof": {
      "type": "string",
      "minLength": 80,
      "maxLength": 256
    },
    "refreshRequestId": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
    }
  },
  "required": [
    "refreshToken",
    "installationId",
    "platform",
    "deviceKeyId",
    "devicePublicJwk",
    "deviceChallengeId",
    "deviceChallengeNonce",
    "deviceProof",
    "refreshRequestId"
  ]
}

JSON 示例（人工数据，不能直接登录）

{
  "installationId": "a7000000-0000-4000-8000-000000000001",
  "devicePublicJwk": {
    "kty": "EC",
    "crv": "P-256",
    "x": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
    "y": "BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB",
    "alg": "ES256",
    "ext": true
  },
  "deviceChallengeId": "a7000000-0000-4000-8000-000000000001",
  "deviceChallengeNonce": "nnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnn",
  "deviceProof": "ssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssssss",
  "refreshToken": "rrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrr",
  "platform": "ios",
  "deviceKeyId": "a7000000-0000-4000-8000-000000000001",
  "refreshRequestId": "a7000000-0000-4000-8000-000000000001"
}

响应

RefreshResponse · 完整字段定义

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "anyOf": [
    {
      "type": "object",
      "properties": {
        "accessToken": {
          "type": "string",
          "minLength": 1
        },
        "refreshToken": {
          "type": "string",
          "minLength": 1
        },
        "expiresAt": {
          "type": "string",
          "format": "date-time",
          "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
        },
        "gameAccountId": {
          "type": "string",
          "format": "uuid",
          "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
        },
        "gameId": {
          "type": "string",
          "format": "uuid",
          "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
        },
        "originAccountLifecycleId": {
          "type": "string",
          "format": "uuid",
          "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
        },
        "deviceKeyId": {
          "type": "string",
          "format": "uuid",
          "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
        },
        "created": {
          "type": "boolean"
        },
        "principalType": {
          "type": "string",
          "const": "game_account"
        }
      },
      "required": [
        "accessToken",
        "refreshToken",
        "expiresAt",
        "gameAccountId",
        "gameId",
        "originAccountLifecycleId",
        "deviceKeyId",
        "created",
        "principalType"
      ]
    },
    {
      "type": "object",
      "properties": {
        "accessToken": {
          "type": "string",
          "minLength": 1
        },
        "refreshToken": {
          "type": "string",
          "minLength": 1
        },
        "expiresAt": {
          "type": "string",
          "format": "date-time",
          "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
        },
        "principalType": {
          "type": "string",
          "const": "motion_subject"
        },
        "motionSubjectId": {
          "type": "string",
          "format": "uuid",
          "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
        },
        "deviceKeyId": {
          "type": "string",
          "format": "uuid",
          "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
        },
        "created": {
          "type": "boolean",
          "const": false
        }
      },
      "required": [
        "accessToken",
        "refreshToken",
        "expiresAt",
        "principalType",
        "motionSubjectId",
        "deviceKeyId",
        "created"
      ]
    }
  ]
}

JSON 示例（人工数据，不能直接登录）

{
  "accessToken": "synthetic-access-token",
  "refreshToken": "rrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrr",
  "expiresAt": "2026-08-30T00:00:00.000Z",
  "gameAccountId": "a7000000-0000-4000-8000-000000000001",
  "gameId": "a7000000-0000-4000-8000-000000000001",
  "originAccountLifecycleId": "a7000000-0000-4000-8000-000000000001",
  "deviceKeyId": "a7000000-0000-4000-8000-000000000001",
  "created": false,
  "principalType": "game_account"
}

POST 退出当前会话

/v1/auth/logout

无请求体。服务端撤销当前会话；客户端清理本地 token。过期／已撤销会话可返回 401。网络结果未知时不要宣称远端已退出。

认证：Bearer · 幂等键：必填 · 成功：HTTP 200

无请求体

响应

LogoutResponse · 完整字段定义

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "state": {
      "type": "string",
      "const": "revoked"
    }
  },
  "required": [
    "state"
  ]
}

JSON 示例（人工数据，不能直接登录）

{
  "state": "revoked"
}

POST 退出全部游戏会话

/v1/auth/logout-all

无请求体。撤销该游戏账号会话，响应包含 scope=all；不是注销账号或删除存档。

认证：Bearer · 幂等键：必填 · 成功：HTTP 200

无请求体

响应

LogoutAllResponse · 完整字段定义

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "state": {
      "type": "string",
      "const": "revoked"
    },
    "scope": {
      "type": "string",
      "const": "all"
    }
  },
  "required": [
    "state",
    "scope"
  ]
}

JSON 示例（人工数据，不能直接登录）

{
  "state": "revoked",
  "scope": "all"
}

GET 读取当前玩家状态

/v1/me

无请求体。game_account 与 motion_subject 响应不同；首版使用 game_account。blocked、deleting 或 merge_frozen 不能当作可写状态。

认证：Bearer · 幂等键：不要求 · 成功：HTTP 200

无请求体

响应

CurrentPrincipalResponse · 完整字段定义

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "anyOf": [
    {
      "type": "object",
      "properties": {
        "principalType": {
          "type": "string",
          "const": "game_account"
        },
        "gameAccountId": {
          "type": "string",
          "format": "uuid",
          "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
        },
        "gameId": {
          "type": "string",
          "format": "uuid",
          "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
        },
        "accessStatus": {
          "type": "string",
          "enum": [
            "active",
            "blocked"
          ]
        },
        "lifecycleState": {
          "type": "string",
          "enum": [
            "active",
            "deleting",
            "purging",
            "deleted",
            "merged"
          ]
        },
        "mutationState": {
          "type": "string",
          "enum": [
            "active",
            "merge_frozen"
          ]
        },
        "tokenEpoch": {
          "type": "string",
          "pattern": "^\\d+$"
        },
        "lineageId": {
          "type": "string",
          "format": "uuid",
          "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
        },
        "lineageGeneration": {
          "type": "string",
          "pattern": "^\\d+$"
        }
      },
      "required": [
        "principalType",
        "gameAccountId",
        "gameId",
        "accessStatus",
        "lifecycleState",
        "mutationState",
        "tokenEpoch",
        "lineageId",
        "lineageGeneration"
      ]
    },
    {
      "type": "object",
      "properties": {
        "principalType": {
          "type": "string",
          "const": "motion_subject"
        },
        "subjectId": {
          "type": "string",
          "format": "uuid",
          "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
        },
        "scopes": {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      },
      "required": [
        "principalType",
        "subjectId",
        "scopes"
      ]
    }
  ]
}

JSON 示例（人工数据，不能直接登录）

{
  "principalType": "game_account",
  "gameAccountId": "a7000000-0000-4000-8000-000000000001",
  "gameId": "a7000000-0000-4000-8000-000000000001",
  "accessStatus": "active",
  "lifecycleState": "active",
  "mutationState": "active",
  "tokenEpoch": "1",
  "lineageId": "a7000000-0000-4000-8000-000000000001",
  "lineageGeneration": "1"
}

GET 读取玩家资料

/v1/games/{gameId}/profile

未创建时返回 display_fields={}、schema_version=1、revision=0、updated_at=null。gameId 必须与会话一致。

认证：Bearer · 幂等键：不要求 · 成功：HTTP 200

无请求体

响应

ProfileResponse · 完整字段定义

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "display_fields": {
      "type": "object",
      "propertyNames": {
        "type": "string",
        "minLength": 1,
        "maxLength": 64
      },
      "additionalProperties": {
        "anyOf": [
          {
            "type": "string",
            "maxLength": 256
          },
          {
            "type": "number"
          },
          {
            "type": "boolean"
          },
          {
            "type": "null"
          }
        ]
      }
    },
    "schema_version": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "revision": {
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "updated_at": {
      "anyOf": [
        {
          "type": "string",
          "format": "date-time",
          "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "required": [
    "display_fields",
    "schema_version",
    "revision",
    "updated_at"
  ]
}

JSON 示例（人工数据，不能直接登录）

{
  "display_fields": {},
  "schema_version": 1,
  "revision": 0,
  "updated_at": null
}

PATCH 更新玩家资料

/v1/games/{gameId}/profile

带当前 baseRevision，首次为 0。409 REVISION_CONFLICT 时重新读取并由游戏合并／确认，再以新键提交。

认证：Bearer · 幂等键：必填 · 成功：HTTP 200

请求

ProfilePatch · 完整字段定义

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "baseRevision": {
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "displayFields": {
      "type": "object",
      "propertyNames": {
        "type": "string",
        "minLength": 1,
        "maxLength": 64
      },
      "additionalProperties": {
        "anyOf": [
          {
            "type": "string",
            "maxLength": 256
          },
          {
            "type": "number"
          },
          {
            "type": "boolean"
          },
          {
            "type": "null"
          }
        ]
      }
    }
  },
  "required": [
    "baseRevision",
    "displayFields"
  ]
}

JSON 示例（人工数据，不能直接登录）

{
  "baseRevision": 0,
  "displayFields": {
    "nickname": "Ape"
  }
}

响应

ProfilePatchResponse · 完整字段定义

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "revision": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "display_fields": {
      "type": "object",
      "propertyNames": {
        "type": "string",
        "minLength": 1,
        "maxLength": 64
      },
      "additionalProperties": {
        "anyOf": [
          {
            "type": "string",
            "maxLength": 256
          },
          {
            "type": "number"
          },
          {
            "type": "boolean"
          },
          {
            "type": "null"
          }
        ]
      }
    },
    "updated_at": {
      "type": "string",
      "format": "date-time",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
    }
  },
  "required": [
    "revision",
    "display_fields",
    "updated_at"
  ]
}

JSON 示例（人工数据，不能直接登录）

{
  "display_fields": {
    "nickname": "Ape"
  },
  "revision": 1,
  "updated_at": "2026-08-30T00:00:00.000Z"
}

GET 列出存档槽

/v1/games/{gameId}/saves

无请求体。返回 items 和 nextCursor=null，目前不分页。

认证：Bearer · 幂等键：不要求 · 成功：HTTP 200

无请求体

响应

SaveListResponse · 完整字段定义

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "items": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "slot": {
            "type": "string"
          },
          "revision": {
            "type": "integer",
            "exclusiveMinimum": 0,
            "maximum": 9007199254740991
          },
          "content_sha256": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
          }
        },
        "required": [
          "slot",
          "revision",
          "content_sha256",
          "updated_at"
        ]
      }
    },
    "nextCursor": {
      "type": "null"
    }
  },
  "required": [
    "items",
    "nextCursor"
  ]
}

JSON 示例（人工数据，不能直接登录）

{
  "items": [],
  "nextCursor": null
}

GET 读取存档

/v1/games/{gameId}/saves/{slot}

首次没有存档返回 404 NOT_FOUND；客户端保留本地新游戏并以 baseRevision=0 创建。object_key 不是公网 URL；v0.1 示例只接入 inline_document。

认证：Bearer · 幂等键：不要求 · 成功：HTTP 200

无请求体

响应

SaveResponse · 完整字段定义

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "slot": {
      "type": "string"
    },
    "revision": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "content_sha256": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "updated_at": {
      "type": "string",
      "format": "date-time",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
    },
    "inline_document": {
      "anyOf": [
        {
          "type": "object",
          "propertyNames": {
            "type": "string"
          },
          "additionalProperties": {}
        },
        {
          "type": "null"
        }
      ]
    },
    "object_key": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "required": [
    "slot",
    "revision",
    "content_sha256",
    "updated_at",
    "inline_document",
    "object_key"
  ]
}

JSON 示例（人工数据，不能直接登录）

{
  "slot": "main",
  "revision": 1,
  "inline_document": {
    "payload": "level=1;coins=10"
  },
  "object_key": null,
  "content_sha256": "44071ba2692d476892e10184ece8fa877284164929ba14f52025fd6fe0c623fa",
  "updated_at": "2026-08-30T00:00:00.000Z"
}

PUT 保存 JSON 存档

/v1/games/{gameId}/saves/{slot}

document 须是 JSON 对象，JSON.stringify(document) UTF-8 最多 128 KiB；sha256 是这些字节的 64 位小写十六进制 SHA-256（不是排序后 canonical JSON）。重发保留键、baseRevision、document 和 hash；冲突不能自动覆盖。

认证：Bearer · 幂等键：必填 · 成功：HTTP 200

请求

InlineSave · 完整字段定义

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "baseRevision": {
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "document": {
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {}
    },
    "sha256": {
      "type": "string",
      "pattern": "^[a-f0-9]{64}$"
    }
  },
  "required": [
    "baseRevision",
    "document",
    "sha256"
  ]
}

JSON 示例（人工数据，不能直接登录）

{
  "baseRevision": 0,
  "document": {
    "payload": "level=1;coins=10"
  },
  "sha256": "44071ba2692d476892e10184ece8fa877284164929ba14f52025fd6fe0c623fa"
}

响应

SaveWriteResponse · 完整字段定义

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "revision": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "updated_at": {
      "type": "string",
      "format": "date-time",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
    }
  },
  "required": [
    "revision",
    "updated_at"
  ]
}

JSON 示例（人工数据，不能直接登录）

{
  "revision": 1,
  "updated_at": "2026-08-30T00:00:00.000Z"
}

后续接口目录

GET /v1/public/games/{gameSlug}/resources/manifests/{manifestId} · 不在 v0.1 接入承诺内
POST /v1/auth/motion/google · 不在 v0.1 接入承诺内
POST /v1/auth/motion/apple · 不在 v0.1 接入承诺内
POST /v1/auth/motion/google/challenges · 不在 v0.1 接入承诺内
POST /v1/auth/motion/apple/challenges · 不在 v0.1 接入承诺内
POST /v1/auth/motion/authorizations · 不在 v0.1 接入承诺内
GET /v1/me/external-identities · 不在 v0.1 接入承诺内
POST /v1/me/motion/identity/google · 不在 v0.1 接入承诺内
POST /v1/me/motion/identity/apple · 不在 v0.1 接入承诺内
POST /v1/me/motion/identity/google/challenges · 不在 v0.1 接入承诺内
POST /v1/me/motion/identity/apple/challenges · 不在 v0.1 接入承诺内
GET /v1/me/motion/authorization · 不在 v0.1 接入承诺内
PUT /v1/me/motion/authorization · 不在 v0.1 接入承诺内
DELETE /v1/me/motion/authorization · 不在 v0.1 接入承诺内
POST /v1/me/link-challenges · 不在 v0.1 接入承诺内
POST /v1/me/external-identities/{provider}/link · 不在 v0.1 接入承诺内
DELETE /v1/me/external-identities/{linkId} · 不在 v0.1 接入承诺内
GET /v1/me/deletion · 不在 v0.1 接入承诺内
POST /v1/me/deletion-codes · 不在 v0.1 接入承诺内
POST /v1/me/delete · 不在 v0.1 接入承诺内
POST /v1/me/delete/refresh-impact · 不在 v0.1 接入承诺内
POST /v1/me/delete/confirm · 不在 v0.1 接入承诺内
POST /v1/me/delete/cancel · 不在 v0.1 接入承诺内
GET /v1/me/exports · 不在 v0.1 接入承诺内
POST /v1/me/exports · 不在 v0.1 接入承诺内
GET /v1/me/exports/{requestId} · 不在 v0.1 接入承诺内
GET /v1/me/exports/{requestId}/download · 不在 v0.1 接入承诺内
POST /v1/games/{gameId}/saves/{slot}/uploads · 不在 v0.1 接入承诺内
PUT /v1/games/{gameId}/saves/{slot}/uploads/{uploadId}/content · 不在 v0.1 接入承诺内
POST /v1/games/{gameId}/saves/{slot}/uploads/{uploadId}/finalize · 不在 v0.1 接入承诺内
DELETE /v1/games/{gameId}/saves/{slot}/uploads/{uploadId} · 不在 v0.1 接入承诺内
GET /v1/games/{gameId}/progress · 不在 v0.1 接入承诺内
PUT /v1/games/{gameId}/progress · 不在 v0.1 接入承诺内
POST /v1/games/{gameId}/achievements/{code}/progress · 不在 v0.1 接入承诺内
GET /v1/games/{gameId}/announcements · 不在 v0.1 接入承诺内
POST /v1/games/{gameId}/purchase-intents · 不在 v0.1 接入承诺内
POST /v1/games/{gameId}/purchases/apple/verify · 不在 v0.1 接入承诺内
POST /v1/games/{gameId}/purchases/google/verify · 不在 v0.1 接入承诺内
POST /v1/games/{gameId}/purchases/non-consumables/restore · 不在 v0.1 接入承诺内
POST /v1/games/{gameId}/purchases/unbound-claims/challenges · 不在 v0.1 接入承诺内
POST /v1/games/{gameId}/purchases/unbound-claims · 不在 v0.1 接入承诺内
POST /v1/games/{gameId}/integrity/apple/challenges · 不在 v0.1 接入承诺内
POST /v1/games/{gameId}/integrity/apple/register · 不在 v0.1 接入承诺内
POST /v1/games/{gameId}/purchases/claims · 不在 v0.1 接入承诺内
GET /v1/games/{gameId}/purchases/claims/{claimId} · 不在 v0.1 接入承诺内
DELETE /v1/games/{gameId}/purchases/claims/{claimId} · 不在 v0.1 接入承诺内
POST /v1/games/{gameId}/purchases/claims/{claimId}/finalize · 不在 v0.1 接入承诺内
GET /v1/games/{gameId}/purchases/deliveries · 不在 v0.1 接入承诺内
GET /v1/games/{gameId}/entitlements · 不在 v0.1 接入承诺内
GET /v1/games/{gameId}/inventory · 不在 v0.1 接入承诺内
GET /v1/games/{gameId}/inventory/ledger · 不在 v0.1 接入承诺内
POST /v1/games/{gameId}/inventory/consume · 不在 v0.1 接入承诺内
POST /v1/games/{gameId}/motion/sessions · 不在 v0.1 接入承诺内
GET /v1/games/{gameId}/motion/sessions · 不在 v0.1 接入承诺内
GET /v1/games/{gameId}/motion/sessions/{clientSessionId} · 不在 v0.1 接入承诺内
POST /v1/games/{gameId}/motion/sessions/{clientSessionId}/checkpoints · 不在 v0.1 接入承诺内
POST /v1/games/{gameId}/motion/sessions/{clientSessionId}/finalize · 不在 v0.1 接入承诺内
GET /v1/games/{gameId}/motion/summary · 不在 v0.1 接入承诺内
GET /v1/me/motion/summary · 不在 v0.1 接入承诺内
GET /v1/me/motion/by-game · 不在 v0.1 接入承诺内
POST /v1/games/{gameId}/leaderboards/{boardId}/scores · 不在 v0.1 接入承诺内
GET /v1/games/{gameId}/leaderboards/{boardId}/entries · 不在 v0.1 接入承诺内
GET /v1/games/{gameId}/leaderboards/{boardId}/me · 不在 v0.1 接入承诺内
GET /v1/games/{gameId}/inbox · 不在 v0.1 接入承诺内
POST /v1/games/{gameId}/inbox/{messageId}/claim · 不在 v0.1 接入承诺内
POST /v1/me/account-merges · 不在 v0.1 接入承诺内
POST /v1/me/account-merges/{mergeId}/preflight · 不在 v0.1 接入承诺内
POST /v1/me/account-merges/{mergeId}/commit · 不在 v0.1 接入承诺内
POST /v1/me/account-merges/{mergeId}/cancel · 不在 v0.1 接入承诺内
GET /v1/me/account-merges/{mergeId} · 不在 v0.1 接入承诺内
POST /v1/me/commerce-recovery-credentials · 不在 v0.1 接入承诺内
GET /v1/me/commerce-recovery-credentials · 不在 v0.1 接入承诺内
DELETE /v1/me/commerce-recovery-credentials/{credentialId} · 不在 v0.1 接入承诺内
POST /v1/me/commerce-recovery-credentials/{credentialId}/acknowledge · 不在 v0.1 接入承诺内

错误结构与状态映射

ProblemDetails · 完整字段定义

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "type": {
      "type": "string",
      "format": "uri"
    },
    "title": {
      "type": "string"
    },
    "status": {
      "type": "integer",
      "minimum": 400,
      "maximum": 599
    },
    "code": {
      "type": "string",
      "enum": [
        "BAD_REQUEST",
        "AUTHENTICATION_REQUIRED",
        "AUTHORIZATION_DENIED",
        "ACCOUNT_BLOCKED",
        "ACCOUNT_NOT_ACTIVE",
        "ACCOUNT_MUTATION_FROZEN",
        "GAME_SCOPE_MISMATCH",
        "PROVIDER_NOT_ALLOWED",
        "IDEMPOTENCY_KEY_REQUIRED",
        "IDEMPOTENCY_CONFLICT",
        "IDEMPOTENCY_IN_PROGRESS",
        "EXTERNAL_IDENTITY_PROOF_REISSUE_REQUIRED",
        "REVISION_CONFLICT",
        "RATE_LIMITED",
        "NOT_FOUND",
        "PAYLOAD_TOO_LARGE",
        "CHECKSUM_MISMATCH",
        "MOTION_AUTHORIZATION_REQUIRED",
        "MOTION_SEQUENCE_CONFLICT",
        "OWNED_BY_ANOTHER_ACCOUNT",
        "UNSUPPORTED_PURCHASE",
        "RECOVERY_CREDENTIAL_UNACKNOWLEDGED",
        "CREDENTIAL_LIMIT_REACHED",
        "CREDENTIAL_LIMIT_CONFLICT",
        "CREDENTIAL_ALREADY_CONSUMED",
        "ROOT_NOT_YET_CLAIMABLE",
        "TRANSFER_LIMIT_EXCEEDED",
        "DELETION_CONFIRMATION_STALE",
        "DELETION_SCOPE_CONFLICT",
        "MERGE_CONTROL_REQUIRED",
        "EXTERNAL_DEPENDENCY_UNAVAILABLE",
        "INTERNAL_ERROR"
      ]
    },
    "requestId": {
      "type": "string",
      "minLength": 1
    },
    "detail": {
      "type": "string"
    },
    "details": {
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {}
    }
  },
  "required": [
    "type",
    "title",
    "status",
    "code",
    "requestId"
  ]
}

JSON 示例（人工数据，不能直接登录）

{
  "type": "https://api.example.com/problems/revision-conflict",
  "title": "REVISION_CONFLICT",
  "status": 409,
  "code": "REVISION_CONFLICT",
  "requestId": "a7000000-0000-4000-8000-000000000001",
  "detail": "Save revision conflict"
}

code	HTTP status
`BAD_REQUEST`	400
`AUTHENTICATION_REQUIRED`	401
`AUTHORIZATION_DENIED`	403
`ACCOUNT_BLOCKED`	403
`ACCOUNT_NOT_ACTIVE`	409
`ACCOUNT_MUTATION_FROZEN`	409
`GAME_SCOPE_MISMATCH`	403
`PROVIDER_NOT_ALLOWED`	403
`IDEMPOTENCY_KEY_REQUIRED`	400
`IDEMPOTENCY_CONFLICT`	409
`IDEMPOTENCY_IN_PROGRESS`	409
`EXTERNAL_IDENTITY_PROOF_REISSUE_REQUIRED`	409
`REVISION_CONFLICT`	409
`RATE_LIMITED`	429
`NOT_FOUND`	404
`PAYLOAD_TOO_LARGE`	413
`CHECKSUM_MISMATCH`	422
`MOTION_AUTHORIZATION_REQUIRED`	403
`MOTION_SEQUENCE_CONFLICT`	409
`OWNED_BY_ANOTHER_ACCOUNT`	409
`UNSUPPORTED_PURCHASE`	422
`RECOVERY_CREDENTIAL_UNACKNOWLEDGED`	409
`CREDENTIAL_LIMIT_REACHED`	409
`CREDENTIAL_LIMIT_CONFLICT`	409
`CREDENTIAL_ALREADY_CONSUMED`	409
`ROOT_NOT_YET_CLAIMABLE`	409
`TRANSFER_LIMIT_EXCEEDED`	409
`DELETION_CONFIRMATION_STALE`	409
`DELETION_SCOPE_CONFLICT`	409
`MERGE_CONTROL_REQUIRED`	403
`EXTERNAL_DEPENDENCY_UNAVAILABLE`	503
`INTERNAL_ERROR`	500