API参考资料

本章节包含了关于now.gg用户账户服务（User Account Service）的API参考资料。

验证令牌API（Verify Token API）

此文档主要关注验证令牌API的详细信息及其运用。

基础URL（Base URL）

https://now.gg

描述（Description）

此API可用于验证所生成的令牌（token）。

请求方法（Request Method）

POST

请求路径（Request Path）

/accounts/oauth2/v1/verify-token

请求头（Request Header）

Content-Type: application/json

请求主体（Request Body）

下列参数应被用在验证API（Verify API）的请求主体之中：

{
     token_type: <token_type>,
     token: <token>,
     client_id: <client_id>,
     client_secret: <client_secret>
 }

请求主体参数

参数	类型	是否必需	允许的值	描述
token_type	string	是	id_token, token	被请求令牌的类型
token	string	是	id_token, token	通过now.gg所生成的有效 id_token 或 token（更多信息）
client_id	string	是	Oauth client_id	通过now.gg账户管理生成的唯一的client_id
client_secret	string	是，如果令牌类型是token 否，如果令牌类型是id_token	Oauth client_secret	通过now.gg账户管理生成的唯一的 client_secret

重要信息

OAuth证书（OAuth credentials）（client_id 和 client_secret）可以通过本章节申请。
id_token：用来验证用户的身份。它提供了关于用户和认证事件的详细信息。
- id_token 被用于基本登录流程。
- 此流程适用于大多数的应用。然而，如果应用需要较高级的集成，那么它可以集成基于令牌的高级登录集成流程。
token: 用于授权访问受保护的资源（APIs）。它决定了客户端可以代表用户采取何种行为。
- token 被用于高级登录集成流程。

预期响应

成功

{ 
     "success": true, 
     "code": "VERIFICATION_SUCCESS", 
     "decodedData": {}, 
     "msg": "Token Verification success" 
 }

失败

{ 
     "success": false, 
     "code": "EXPIRED_TOKEN", 
     "msg": "Token Expired!" 
 }

{
    "success": false,
    "code": "INVALID_TOKEN",
    "msg": "Token Invalid for given ClientId/ClientSecret"
 }

响应参数

参数	类型	可能的取值	描述
success	boolean	True, False	返回结果为True或False
code	string	VERIFICATION_SUCCESS INVALID_TOKEN EXPIRED_TOKEN	VERIFICATION_SUCCESS：对于client_id/client_secret的令牌验证成功 INVALID_TOKEN：令牌格式错误，或是‘aud’与您的client_id不匹配 EXPIRED_TOKEN：令牌过期
msg	string	Token Verification Success Token Expired Token Invalid for given ClientId/ClientSecret	与返回码相关联，描述成功/失败的易于理解的消息
decodedData	dict/obj		成功之后返回的解码数据

解码数据示例

1. 使用id_token返回的解码数据

{ 
      "iss": 'https://now.gg', // id_token的发行者，   
      "sub": <>, <sub>, 
      "aud": client_id,// 所生成令牌的唯一client_id 
      "exp": <>,// 令牌过期的时间
      "iat": <>, // 令牌发行的纪元时间戳 
      "auth_time": <>, // 认证完成的时间 
      "email": <>, // 用户的email id 
      "mobile": <> // 带有国家代码前缀的用户手机号 
      "userId": <> // 唯一的用户标识符 
      "name": <>, // 用户全名 
      "picture": <>, // 个人资料图片url
      "countryCode":<>, // 用户的国家代码
 }

2. 使用令牌（Token）返回的解码数据

{ 
       "iss": "https://now.gg", // token的发行者
       "tokenId": "token_id", // token_id 
       "aud": "client_id", // client_id 
       "sessionId": "sessionId", // 会话id 
       "userId": "userId" , // 用户Id
       "scope": "email", // 授权范围，包括：email/profile/authorization 
       "iat": 1636779002, 
       "exp": 1636782602 
 }

解码数据参数

参数	类型	可用于	描述
Iss	string	id_token, token	令牌（Token）发行者
sub	string	id_token	反映uuid/ulid的随机唯一字符串
aud	string	id_token, token	所生成令牌的唯一client_id
picture	string	id_token	用户个人资料图片url
exp	int	id_token, token	请求有效期 – 令牌过期时间
iat	int	id_token, token	令牌发行的纪元时间戳
auth_time	int	id_token	认证完成的时间
email	string	id_token	用户关联的账户的电子邮箱地址
mobile	string	id_token	带有国家名称（country name）前缀的用户手机号
userId	string	id_token, token	用户的唯一标识符
name	string	id_token	用户全名
countryCode	string	id_token	用户的国家代码
tokenId	string	token	返回令牌的tokenId
sessionId	string	token	授权的会话ID
scope	string	token	授权范围，包括：email/profile/authorization

令牌生成API（Generate Tokens API）

本文档主要关注令牌生成API（Generate Tokens API）的详细信息及其运用。

基础URL（Base URL）

https://now.gg

描述（Description）

此API被用于使用授权码来生成 token 和 refresh_token。

请求方法（Request Method）

POST

请求路径（Request Path）

/accounts/oauth2/v1/token

请求头（Request Header）

Content-Type: application/json

请求主体（Request Body）

下列请求主体应用于使用令牌生成API来生成 token 和 refresh_token。

注意：如果您要使用refresh_token来生成令牌，那么请参阅此章节。

{
  client_secret: '<your_oauth_client_secret>',
  client_id: '<your_oauth_client_id>',
  grant_type: 'code',
  code:  '<通过账户管理收到的authorization_code>',
  token_type: '<refresh_token token>',
}

请求主体参数

参数	类型	是否必需	允许的值	描述
token_type	string	是	refresh_token, token	被请求令牌的类型。
grant_type	string	是	code	授权（码）的类型。
code	string	是	Auth Code	通过账户管理接收到的authorization_code。
client_id	string	是	OAuth client_id	唯一的OAuth client_id。
client_secret	string	是	OAuth client_secret	唯一的OAuth client_secret。

注意：OAuth证书（client_id and client_secret）可通过此章节申请。

预期响应

{
 "success": true,
 "code": "REFRESH_TOKEN TOKEN",
 "token": "<token>", // 用于授权头的令牌。
 "refresh_token": "<refresh_token>", // 当令牌过期时，用于生成新的令牌。
 "token_expiry": "<token_expiry_time>", // 令牌过期时间
 "refresh_token_expiry": "<refresh_token_expiry>" // refresh_token过期时间
 }

响应参数

参数	类型	描述
success	boolean	True – 操作成功。 False – 操作失败。
code	string	REFRESH_TOKEN TOKEN.
token	string	用于授权头（Authorization header）的令牌。
refresh_token	string	当令牌过期时，用于生成新的令牌。
token_expiry	string	返回令牌的过期时间。
refresh_token_expiry	string	返回refresh_token的过期时间。

用refresh_token生成令牌

如果您的 token 已经过期，那么使用 refresh_token 来生成令牌。

请求主体

{
  client_secret: '<your_oauth_client_secret>',
  client_id: '<your_oauth_client_id>',
  grant_type: 'refresh_token',
  refresh_token:  '<refresh_token>',
  token_type: '<token>',
}

请求参数

参数	类型	是否必需	允许的值	描述
token_type	string	是	token	被请求的令牌类型。
grant_type	string	是	refresh_token	授权（refresh_token）的类型。
refresh_token	string	是	refresh_token	您之前生成的refresh_token。
client_id	string	是	OAuth client_id	唯一的OAuth client_id。
client_secret	string	是	OAuth client_secret	唯一的OAuth client_secret。

预期响应

{
 "success": true,
 "code": "<REFRESH_TOKEN TOKEN>",
 "token": "<token>", // 用于授权头（Authorization Header）的令牌。
 "token_expiry": "<token_expiry>", // 令牌过期时间。
 }

响应参数

参数	类型	描述
success	boolean	True – 操作成功。 False – 操作失败。
code	string	REFRESH_TOKEN TOKEN.
token	string	用于授权头的令牌。
token_expiry	string	返回令牌的过期时间。

用户信息API（User Info API）

此文档主要关注用户信息API（User Info API）的详细信息及其运用。

基础URL（Base URL）

https://now.gg

描述（Description）

此API可用于获取与用户相关的用户信息。

请求方法（Request Method）

GET

请求路径（Request Path）

/accounts/users/v1/userinfo

请求头（Request Header）

您需要在请求头字段中加入Bearer Token来进行授权。

{ Authorization: 'Bearer Token'}

预期响应

当使用用户信息API来获取用户数据时，下列是预期的响应。

{
  success: true,
  code: 'USERDATA',
  userData: {
      email: '', // 用户的电子邮箱地址
      mobile: '', // 用户的手机号码
      userId: '', // 用户的userld
      profilePicture: '', // 个人信息图片URL
      name: '', // 用户的名字
      countryCode: 'IN', // 用户的国家代码
      country: '', // 用户的国家
      countryRegionCode: '', // 用户的国家区域代码
      countryRegion: '', // 用户的国家区域
      city: '', // 用户的城市名称
      postalCode: '', // 用户的邮政编码
  },
}

响应参数

参数	类型	描述
success	boolean	True – 操作成功。 False – 操作失败。
email	string	用户的电子邮箱地址。
mobile	string	带有国家代码作为前缀的用户手机号码。
userId	string	用户账户的唯一标识符。
profilePicture	string	用户个人信息图片的URL。
name	string	用户的全名。
countryCode	string	用户的国家代码。
country	string	用户的国家。
countryRegionCode	string	用户的国家区域（州）代码。
countryRegion	string	用户的国家区域（州）。
city	string	用户的城市。
postalCode	string	用户的邮政编码。
code	string	USERDATA – 用户信息。

会话信息API（Session Info API）

此文档主要关注会话信息API（Session Info API）的详细信息及其运用。

基础URL（Base URL）

https://now.gg

描述（Description）

此API用于获取用户的会话信息。

请求方法（Request Method）

GET

请求路径（Request Path）

/accounts/users/v1/sessioninfo

请求头（Request Header）

您需要在请求头中加入Bearer Token来进行授权。

{ Authorization: 'Bearer Token'}

预期响应

当使用会话信息API（Session Info API）来获取会话数据时，下列是预期的响应。

{
   success: true,
   code: 'USERDATA',
   sessionData: {
       userAgent: '', // user agent信息
       ip: '', // 用户的IP地址
       locale: 'en-GB', // 用户地区
       deviceData: {
           os: {
               version: '', // OS版本
               name: '',   // OS名称
               platform: '', // OS平台
          },
           device: {
               brand: '', // 设备品牌信息
               model: '', // 设备机型信息
               type: 'desktop', // 设备类型
          },
           client: {
               version: '', // 客户端版本
               engine: '', // 客户端引擎
               name: '', // 客户端名称
               type: '', // 客户端类型
               engineVersion: '', // 客户端引擎版本
          },
      },
       geoData: {
           countryCode: '', // 用户的国家代码
           country: '', // 用户的国家
           countryRegionCode: '', // 用户的国家区域代码
           countryRegion: '', // 用户的国家区域
           city: '', // 用户的城市
           postalCode: '', // 用户的邮政编码
      },
       lastSessionTimestamp: '', // 会话时间戳
       packageName: '', // 包名
  },
}

响应参数

参数	类型	描述
success	boolean	True – 操作成功。 False – 操作失败。
code	string	USERDATA – 会话信息。
lastSessionTimestamp	string	上次会话的时间戳。
packageName	string	包名。

会话数据参数

参数	类型	描述
userAgent	string	User-Agent信息。
ip	string	用户的IP地址。
locale	string	用户地区。

设备数据参数

参数	类型	描述
OS
version	string	用户操作系统的版本。
name	string	用户操作系统的名称。
platform	string	用户操作系统的平台。
Device
brand	int	用户设备的品牌。
model	int	用户设备的机型。
type	string	设备类型。
Client
version	string	客户端版本。
engine	string	客户端引擎。
name	string	客户端名称。
type	string	客户端类型。
engineVersion	string	客户端引擎版本。

地理（Geo）数据参数

参数	类型	描述
countryCode	string	用户的国家代码。
country	string	用户的国家。
countryRegionCode	string	用户的国家地区（州）代码。
countryRegion	string	用户的国家地区（州）。
city	string	用户的城市。
postalCode	string	用户的邮政编码。

演示工程

流程图