• 版本：1.0.0
• 服务器：https://login.xsolla.com/api
• 协议：https
• 接受：application/json
• 响应格式：application/json
• 通过邮件与我们联系
• 联系网址： https://xsolla.com/

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

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

• YAML
• JSON

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

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

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

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

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

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

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

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

Login API支持以下令牌类型：

• 用户令牌。用于向以下用户资源发送请求：
  • 个人资料
  • 好友
  • 属性
• 服务器令牌。用于向应用程序资源（如设置或用户数据）发送请求。有以下请求可用：
  • 创建平台帐户
  • 获取用户数据
  • 关联帐户
  • 通过外部ID关联用户帐户

要获取令牌，请发送以下请求之一：

• 用户注册（JWT或OAuth 2.0）
• 通过用户名和密码进行认证（JWT、OAuth 2.0或通过用户名和密码进行JWT认证）
• 通过社交网络进行认证（JWT或OAuth 2.0）
• 静默认证（JWT或OAuth 2.0）
• 通过社交网络访问令牌进行认证
• 通过发布平台进行认证

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.

每个密钥都一个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 — 显示该组是否是默认组（true或false值）。 只能有一个默认组。该组最初包含将用户分到不同组之前的所有用户。
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_agreement的fields参数。
connection_information	string		显示用户是否确认了其出生日期。确认由okname服务进行。

如果使用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认证后包含在令牌中的声明如下。

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

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

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

服务器令牌在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。生成的JWT由一个密钥签名。为确保JWT的相关性以及属于 您登录管理器项目的用户，应验证它的值。

要验证JWT：

1. 在发布商帐户中打开您的项目，然后前往登录管理器部分。
2. 单击登录管理器选项面板中的配置。
3. 在导航页面上，前往安全性区块并选择JWT签名部分。
4. 选择您的加密方法并复制密钥或新公共JSON Web密钥字段的值，具体取决于所选方法。
5. 选择库并将其连接到应用程序的服务器端。
6. 将步骤4中复制的值传递给验证函数条目。

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

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

{
  "error": {
    "code": "000-000",
    "description": "description"
  }
}