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

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

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

• [YAML](https://api.redocly.com/registry/bundle/xsolla/login- api/v1/openapi.yaml?branch=main)
• [JSON](https://api.redocly.com/registry/bundle/xsolla/login- api/v1/openapi.json?branch=main)

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

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

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

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

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

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

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

用于分发游戏的游戏平台（例如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)。

To get a server token:

1. Set up server OAuth 2.0 client.
2. Generate server JWT.

设置服务器OAuth 2.0客户端

1. Open your project in Publisher Account and go to the Login section.
2. Click Configure in the panel of a Login project.
3. Go to the Security block and select the OAuth 2.0 section.
4. Click Add OAuth 2.0.
5. Specify OAuth 2.0 redirect URIs.
6. Check the Server (server-to-server connection) box.
7. Specify Token lifetime.
8. Click Connect.
9. Copy and save the client ID and secret key.

Generate server JWT

On the back end of your application, implement a method to get the server JWT using the Generate JWT API call. The request must contain the following parameters:

• grant_type is the JWT type, 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	字符串	是	给令牌签名的服务：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	字符串		Authentication option: xsolla_login — login via username/email and password. social — social login email — passwordless login via one-time code received by email. phone — passwordless login via one-time code received by SMS. firebase — login via username/email and password when the user data storage is Firebase. playfab — login via username/email and password when the user data storage is PlayFab. proxy — login via username/email and password when the user data storage is custom. device — login with device ID. server_custom_id — login with custom ID. 只能有一个默认组。该组最初包含将用户分到不同组之前的所有用户。
avatar	字符串		User avatar URL.
username	字符串		用户名。
publisher_id	integer		拥有登录管理器项目的商户ID。
email	字符串		用户邮箱地址。
payload	字符串		身份认证过程中在payload参数中传递的附加信息。
promo_email_agreement	boolean		可以是以下值之一： true，如果用户同意接收电子简讯。 false，不同意接收。 默认为true值。 要向登录管理器小组件的注册表单添加该功能： 如使用小组件2.0，请联系您的帐户经理。 如果使用上一版本的小组件，请在初始代码中添加值为promo_email_agreement的fields参数。
connection_information	字符串		显示用户是否确认了其出生日期。确认由okname服务进行。

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

声明	类型	必需	描述
external_account_id	字符串	是	用户PlayFab ID。
session_ticket	字符串	是	认证请求或向PlayFab API发送请求期间收到的SessionTicket参数。 如果通过OAuth 2.0协议来认证用户并向scope参数传入了playfab值，则令牌包含该声明。
entity_token	字符串	是	一个EntityToken.EntityToken参数。
entity_type	字符串	是	一个EntityToken.Entity.Type参数。只能有title_player_account值。
entity_id	字符串	是	一个EntityToken.Entity.Id参数。

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

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

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

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

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

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

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

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

服务器令牌在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	字符串	是	唯一令牌ID。

每个用户在成功认证后都会有一个为其生成的JWT。生成的JWT由一个密钥签名。为确保JWT的相关性以及属于 您登录管理器项目的用户，应验证它的值。

要验证JWT：

1. Open your project in Publisher Account and go to the Login section.
2. Click Configure in the panel of a Login option.
3. On the navigation page, go to the Security block and select the JWT Signature section.
4. Select your encryption method and copy the value of the Secret key or New public JSON Web Key field, depending on the selected method.
5. Choose the library and connect it on the server side of your application.
6. Pass the value, copied in the step 4, to the validation function entry.

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

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

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