Xsolla-logo
  • 文档
  • 创建帐户

概述

本部分介绍用于登录管理器的API调用。发送请求之前请在发布商帐户设置您的登录管理器项目。

IP addresses

The full list of IP addresses that login.xsolla.com may use:

  • 34.94.0.85
  • 34.94.14.95
  • 34.94.25.33
  • 34.94.115.185
  • 34.94.154.26
  • 34.94.173.132
  • 34.102.48.30
  • 35.235.99.248
  • 35.236.32.131
  • 35.236.35.100
  • 35.236.117.164

下载API定义

您可以下载两种格式的API定义:

词汇表

您可以在发布商帐户中访问以下登录管理器项目类型:

  • 标准登录管理器项目
  • 影子登录管理器项目

关于它的详细信息请参阅跨平台帐户功能。

流量限制

Are the restrictions applied by Xsolla API on the frequency of access by a user within a defined timeframe.

标准登录管理器项目

用于存储主帐户的登录管理器项目。

影子登录管理器项目

用于存储平台帐户的登录管理器项目。

主帐户

一种在标准登录管理器项目中创建的且关联了平台帐户的帐户类型。主帐户用于在不同平台上识别玩家。

平台帐户

一种在影子登录管理器项目中创建的且关联了指定发布平台的帐户类型。一个平台帐户不能关联其他平台帐户。另外,不能解除帐户与主帐户的关联。

发布平台

用于分发游戏的游戏平台(例如Steam、PlayStation、Xbox等)。

身份认证

Login API支持以下令牌类型:

Authentication schemes

您可以按照身份认证机制来判断一个API调用属于客户端侧还是服务器侧:

  • Client-side — are called without authentication or with the Authorization header: Bearer <user_JWT> header, where <user_JWT> — is the user token.
  • Server-side API calls for implementing the user flow — are called with the header: X-SERVER-AUTHORIZATION: <server_JWT>, where <server_JWT> — is the server token.

获取用户令牌

要获取令牌,请发送以下请求之一:

JWT认证后,用户将重定向到在查询参数中包含令牌的回调URL:<Callback URL>?token=<User token (JWT)>

进行基于OAuth 2.0协议的认证后,请将生成JWT请求发送给艾克索拉登录管理器服务器来用收到的code交换用户令牌(access_token)。

获取服务器令牌

要获取服务器令牌:

  1. 设置服务器OAuth 2.0 客户端
  2. 生成服务器JWT

设置服务器OAuth 2.0客户端

  1. 发布商帐户中打开您的项目,然后前往登录管理器部分
  2. 登录管理器项目的面板中单击配置
  3. 前往安全性区块并选择OAuth 2.0部分。
  4. Click Add OAuth 2.0 Client.
  5. 勾选服务器(服务器对服务器连接)复选框。
  6. 指定令牌有效期
  7. 单击连接
  8. 复制并保存客户端ID和密钥。

生成服务器JWT

在应用程序的后端,实现使用生成JWT API调用获取服务器JWT的方法。请求必须包含以下参数:

  • grant_type is the type of getting JWT, pass the client_credentials value.
  • client_secret is the secret key that is received when you set up the server OAuth 2.0 client.
  • client_id is the client ID received when you set up the server OAuth 2.0 client.

流量限制

To prevent Xsolla system overloads and protect against sudden spikes in incoming traffic, Xsolla limits the number of requests received by the Xsolla API within a specified period of time. If the limit is exceeded, the Xsolla API returns an HTTP response with the 429 status code.

Rate limits vary by method, IP-address, authentication scheme, and other factors.

Rate limits for server-side methods are applied to methods with server-side authentication — methods that are called with the X-SERVER-AUTHORIZATION: <server_JWT> header, where <server_JWT> is the server token.

Rate limits for client-side methods are applied to methods without authentication or with client-side authentication — methods that are called with the Authorization: Bearer <user_JWT> header, where <user_JWT> is the user token.

Example of a method with server-side authentication: Example of a 
method with server-side 
authentication Example of a method with client-side authentication: Example of a method with server-side 
authentication

Rate limits for client-side methods do not change and are necessary to prevent brute-force attacks. The maximum request rate for server-side methods is higher than for client-side methods. You can refer to the recommendations on how to manage rate limits in the documentation.

Note In certain cases, it is possible to adjust the rate limits by request. To request the rate limits adjustment, contact your Customer Success Manager or email csm@xsolla.com.

JWT结构

每个密钥都一个JWT格式,并在负载中包含固定的信息。

用户JWT

用户JWT是作为身份认证或注册结果收到的一个令牌。令牌负载包含关于用户和认证调用的信息。

通过OAuth 2.0协议获取用户令牌需要OAuth 2.0客户端。用户令牌在Authorization: Bearer <JWT>头中传入。

主要声明

身份认证或邮箱地址确认后,令牌会包含主要声明。这些声明的存在不依赖于用户数据库和认证调用。

 
声明 类型 必需 描述
exp Unix时间戳 令牌过期的日期和时间。默认过期时间是24小时。您可以更改各登录管理器项目的过期时间。
iss string 给令牌签名的服务:https://login.xsolla.com
iat Unix时间戳 授予令牌的日期和时间。
sub 字符串(UUID) 写入在艾克索拉登录管理器服务器侧的用户ID。
groups array

用户所在组的列表。每个组的写入格式如下:

  • id — 组ID
  • name — 组名称
  • is_default — 显示该组是否是默认组(truefalse值)。

只能有一个默认组。该组最初包含将用户分到不同组之前的所有用户。

xsolla_login_project_id 字符串(UUID) 登录管理器项目ID。
type string

身份认证选项:

  • xsolla_login — 通过用户名/邮箱和密码登录。
  • social — 社交网络登录
  • email — 通过电子邮件接收的一次性代码进行无密码登录。
  • phone — 通过短信接收的一次性代码进行无密码登录。
  • firebase — 用户数据存储为Firebase时,通过用户名/邮箱和密码登录。
  • playfab — 用户数据存储为PlayFab时,通过用户名/邮箱和密码登录。
  • proxy — 用户数据存储为自定义时,通过用户名/邮箱和密码登录。
  • device — 使用设备ID登录。
  • server_custom_id — 使用自定义ID登录。

只能有一个默认组。该组最初包含将用户分到不同组之前的所有用户。

avatar string 用户头像URL。
username string 用户名。
publisher_id integer 拥有登录管理器项目的商户ID。
email string 用户邮箱地址。
payload string 身份认证过程中在payload参数中传递的附加信息。
promo_email_agreement boolean

可以是以下值之一:

  • true,如果用户同意接收电子简讯。
  • false,不同意接收。
默认为true值。

要向登录管理器小组件的注册表单添加该功能:

  • 如使用小组件2.0,请联系您的帐户经理。
  • 如果使用上一版本的小组件,请在初始代码中添加值为promo_email_agreementfields参数。

connection_information string 显示用户是否确认了其出生日期。确认由okname服务进行。

PlayFab存储

如果使用PlayFab存储,身份认证后包含在令牌中的声明如下。

声明 类型 必需 描述
external_account_id string 用户PlayFab ID。
session_ticket string

认证请求或向PlayFab API发送请求期间收到的SessionTicket参数。

如果通过OAuth 2.0协议来认证用户并向scope参数传入了playfab值,则令牌包含该声明。

entity_token string 一个EntityToken.EntityToken参数。
entity_type string 一个EntityToken.Entity.Type参数。只能有title_player_account值。
entity_id string 一个EntityToken.Entity.Id参数。

自定义存储

如果使用自定义存储,身份认证后包含在令牌中的声明如下。

声明 类型 必需 描述
provider string 认证使用的社交网络的名称。如果用户通过用户名和密码进行认证,则声明的值为xsolla
external_account_id string 您服务器侧的用户ID。
partner_data 认证过程中您服务器在响应正文中返回的任何类型的数据。

社交网络帐户认证

通过社交网络进行认证后包含在令牌中的声明如下。这些声明的存在不依赖于用户数据库。

声明 类型 必需 描述
provider string 认证使用的社交网络的名称。
id string 社交网络中的用户ID。
is_cross_auth boolean 显示静默认证请求正在进行中。
social_access_token string 用于认证的社交网络帐户access_token参数。请联系您的帐户经理设置该功能。
picture 字符串(URL) 社交网络中用户个人资料图片的链接。
birthday 日期(RFC3339) 社交网络中的用户出生日期。
gender string 社交网络中的用户性别。
name string 社交网络中的用户昵称。

通过OAuth 2.0协议进行认证

OAuth 2.0认证后包含在令牌中的声明如下。

声明 类型 必需 描述
jti string 唯一令牌ID。

通过手机号码进行认证

通过手机号码进行认证后包含在令牌中的声明如下。

声明 类型 必需 描述
phone_number string 用于认证的用户手机号码。手机号码格式由国家代码、地区代码和线路号码组成,没有分隔符。

服务器JWT

服务器令牌在X-SERVER-AUTHORIZATION头中传入。

令牌负载包含OAuth 2.0客户端拥有的资源的信息。令牌可以访问对这些资源有基于服务器认证的调用。

声明 类型 必需 描述
xsolla_login_project_id 字符串(UUID) OAuth 2.0客户端所属登录管理器项目的ID。
resources array

OAuth 2.0客户端拥有的资源的列表。可能的资源类型:

  • publisher_id — 拥有该登录管理器项目的商户的资源
  • publisher_project_id发布商帐户中项目的资源。

各组的写入格式如下:

  • name — 资源类型
  • value — 资源ID

jti string 唯一令牌ID。

JWT验证

To validate the JWT, use the following Login API calls:

注意

请勿将密钥告诉任何人。如果发生密钥泄露,请立即更新。

错误

对于错误响应,艾克索拉登录管理器服务器返回包含以下字段的JSON对象:

字段 类型 描述
code string 艾克索拉登录管理器服务器错误代码。
description string 错误描述。文本始终为英文。发生错误时不要使用此文本,因为文本值将来可能会更改。
{
  "error": {
    "code": "000-000",
    "description": "description"
  }
}

400 错误的请求

代码 描述
0 请求包含无效参数。
010-019 客户端认证失败(例如客户端未知、不包含客户端认证或认证方式不支持)。
010-022 缺少参数状态或状态太弱(少于8个字符)。
010-023 授权或筛选令牌无效、过期、撤回、不匹配授权请求中的重定向URI或已发给另一客户端。

401 未授权

代码 描述
002-016 令牌无效。
002-040 无法授权被封禁的用户。
003-001 用户名或密码错误。
003-007 用户帐户未验证。
003-025 获取OAuth 2.0访问令牌时发生错误。
003-040 未授权的用户。
010-026 艾克索拉登录管理器服务器或资源所有者拒绝了请求。

403 被禁止

代码 描述
1901-0001 令牌无效。

404 未找到

代码 描述
003-002 找不到用户。
003-019 未找到项目。
003-061 未找到对象。

418 我是茶壶

代码 描述
004-001 发生了一些问题。

422 无法处理的实体

代码 描述
0 查询中缺少昵称。
002-050 用户的双因素认证设置未更改。
003-003 已存在该用户名的用户。
003-020 调用对此登录管理器项目不可用。
003-022 此登录管理器项目配置错误。请在艾克索拉发布商帐户中更改此登录管理器项目设置或联系您的帐户经理。
003-033 项目类型不匹配。
006-003 只有授权类型为client_credentials的OAuth 2.0客户端有访问列表。
010-015 社交网络认证失败:SERVICE_NAME。
010-016 此社交网络帐户已关联其他用户。
010-032 此登录管理器项目未启用通过该社交网络进行认证。请在您的艾克索拉发布商帐户 > 登录管理器 > 登录管理器项目 > 社交网络连接中启用。
030-024 此登录管理器项目禁用了密码重置。
2002-0001 属性重复。

429 请求过多

代码 描述
002-054 超过允许的搜索尝试次数。请等待一秒后再进行下次请求。
010-005 超过允许的请求次数。
1900-0001 超过允许的请求次数。