Xsolla-logoXsolla Developers
前往发布商帐户

概述

本部分介绍用于登录管理器的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 Data of any type returned by your server in the response body during authentication. To enable the transmission of this claim, contact your Customer Success Manager or email to csm@xsolla.com
social_access_token Access token of the social network through which the user was authenticated. To enable the transmission of this claim, contact your Customer Success Manager or email to csm@xsolla.com.

社交网络帐户认证

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

声明 类型 必需 描述
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:

注意

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

错误

Refer to the documentation for information about Xsolla Login API errors.