https://login.xsolla.com/api
The full list of IP addresses that login.xsolla.com may use:
Are the restrictions applied by Xsolla API on the frequency of access by a user within a defined timeframe.
Login API支持以下令牌类型:
您可以按照身份认证机制来判断一个API调用属于客户端侧还是服务器侧:
Authorization
header: Bearer <user_JWT>
header,
where <user_JWT>
— is the user token.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
)。
要获取服务器令牌:
在应用程序的后端,实现使用生成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 client-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.
每个密钥都一个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 | 是 |
用户所在组的列表。每个组的写入格式如下:
只能有一个默认组。该组最初包含将用户分到不同组之前的所有用户。 |
xsolla_login_project_id |
字符串(UUID) | 是 | 登录管理器项目ID。 |
type |
string |
身份认证选项:
只能有一个默认组。该组最初包含将用户分到不同组之前的所有用户。 |
|
avatar |
string | 用户头像URL。 | |
username |
string | 用户名。 | |
publisher_id |
integer | 拥有登录管理器项目的商户ID。 | |
email |
string | 用户邮箱地址。 | |
payload |
string | 身份认证过程中在payload参数中传递的附加信息。 | |
promo_email_agreement |
boolean |
可以是以下值之一:
true 值。
要向登录管理器小组件的注册表单添加该功能:
|
|
connection_information |
string | 显示用户是否确认了其出生日期。确认由okname服务进行。 |
如果使用PlayFab存储,身份认证后包含在令牌中的声明如下。
声明 | 类型 | 必需 | 描述 |
external_account_id |
string | 是 | 用户PlayFab ID。 |
session_ticket |
string | 是 |
认证请求或向PlayFab API发送请求期间收到的SessionTicket参数。 如果通过OAuth 2.0协议来认证用户并向 |
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 | 社交网络中的用户昵称。 |
通过手机号码进行认证后包含在令牌中的声明如下。
声明 | 类型 | 必需 | 描述 |
phone_number |
string | 是 | 用于认证的用户手机号码。手机号码格式由国家代码、地区代码和线路号码组成,没有分隔符。 |
服务器令牌在X-SERVER-AUTHORIZATION
头中传入。
令牌负载包含OAuth 2.0客户端拥有的资源的信息。令牌可以访问对这些资源有基于服务器认证的调用。
声明 | 类型 | 必需 | 描述 |
xsolla_login_project_id |
字符串(UUID) | 是 | OAuth 2.0客户端所属登录管理器项目的ID。 |
resources |
array | 是 |
OAuth 2.0客户端拥有的资源的列表。可能的资源类型:
各组的写入格式如下:
|
jti |
string | 是 | 唯一令牌ID。 |
To validate the JWT, use the following Login API calls:
注意
请勿将密钥告诉任何人。如果发生密钥泄露,请立即更新。
对于错误响应,艾克索拉登录管理器服务器返回包含以下字段的JSON对象:
字段 | 类型 | 描述 |
code | string | 艾克索拉登录管理器服务器错误代码。 |
description | string | 错误描述。文本始终为英文。发生错误时不要使用此文本,因为文本值将来可能会更改。 |
{
"error": {
"code": "000-000",
"description": "description"
}
}
代码 | 描述 |
0 | 请求包含无效参数。 |
010-019 | 客户端认证失败(例如客户端未知、不包含客户端认证或认证方式不支持)。 |
010-022 | 缺少参数状态或状态太弱(少于8个字符)。 |
010-023 | 授权或筛选令牌无效、过期、撤回、不匹配授权请求中的重定向URI或已发给另一客户端。 |
代码 | 描述 |
002-016 | 令牌无效。 |
002-040 | 无法授权被封禁的用户。 |
003-001 | 用户名或密码错误。 |
003-007 | 用户帐户未验证。 |
003-025 | 获取OAuth 2.0访问令牌时发生错误。 |
003-040 | 未授权的用户。 |
010-026 | 艾克索拉登录管理器服务器或资源所有者拒绝了请求。 |
代码 | 描述 |
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 | 属性重复。 |