会话鉴权 — API 参考

控制台会话：由浏览器持有的凭据，也是浏览器唯一使用的凭据。API 密钥是用于机器通信的机器凭据，绝不能在前端网页中调用。

对用户而言登录仅需一步操作：网页拉取签名挑战挑战码（POST /v1/accounts/challenge），钱包对其进行签名 —— 免费、无需链上交易、任何私钥都不离开钱包 —— 然后签名发送至 POST /v1/session，后者会写入一个带有 httpOnly 属性的 Cookie。该会话在页面刷新和路由跳转后保持有效，在使用中会自动向后顺延，并可通过 GET /v1/session 在后台静默恢复。

由于该凭据为 Cookie，每个可能改变状态的不安全 HTTP 请求方法均需额外携带 X-CSRF-Token 请求头，其值为会话响应中的 csrf_token。跨站页面无法读取该响应，因此无法伪造该头部。

基于 openapi.yaml 在构建时生成。基准 URL 为 https://api.tenergy.me/v1，Nile 测试网环境为 https://api-nile.tenergy.me/v1（详见环境说明）。下述每个请求均遵循身份鉴权规范进行签名，除非鉴权行另有说明。

静默恢复会话

GET /v1/session · getSession

鉴权： 控制台会话 Cookie + X-CSRF-Token。

控制台在每次页面加载时调用。返回当前有效会话，若浏览器中不存在有效会话则返回 1013 session_expired —— 这并不是需要向用户报错的异常，而仅是显示登录弹窗或界面的信号。

响应

响应字段 (Session)

登录进入控制台

POST /v1/session · createSession

鉴权： 公开 —— 无需凭据。

校验由 TRON 地址签名的挑战挑战码并建立浏览器会话，作为带有 httpOnly 标志的 Cookie 返回。如果该地址在该品牌平台尚未创建账户，系统会自动创建一个状态为 status: unfunded 的新账户（与直接调用 POST /v1/accounts 相同），因此首次访问与再次访问的流程完全一致。

对挑战码进行签名是完全免费且无需发起区块链交易的：不转移任何资金，任何密钥均不出钱包。

响应体包含 csrf_token。在随后的所有 POST、PATCH 或 DELETE 请求中，均需将其作为 X-CSRF-Token 头部发送。

请求体

JSON (SessionRequest)，必填。

响应

响应字段 (Session)

退出登录

DELETE /v1/session · deleteSession

鉴权： 控制台会话 Cookie + X-CSRF-Token。

在服务端撤销当前会话并清除 Cookie。同一账户在其他浏览器或设备上的会话不受影响。

响应

延长会话有效时间

POST /v1/session/refresh · refreshSession

鉴权： 控制台会话 Cookie + X-CSRF-Token。

将过期时间顺延并以最新的有效期重新签发 Cookie。日常正常使用时会话也会自动续期，本接口主要用于在长久没有发生请求的页面中主动续约。

响应

响应字段 (Session)

在所有设备上登出

POST /v1/session/revoke-all · revokeAllSessions

鉴权： 控制台会话 Cookie + X-CSRF-Token。

撤销当前已登录钱包在该账户下的所有会话（包括所有浏览器和移动设备，以及当前会话）并清除 Cookie。其他成员的会话不受影响。会写入审计日志（session.revoke_all）。仅限控制台会话，需具备 viewer 或更高成员角色；拒绝任何 API 密钥。

响应

最近登录历史

GET /v1/session/history · getSessionHistory

鉴权： 控制台会话 Cookie + X-CSRF-Token。

返回当前已登录钱包在该账户下的最近十次控制台登录记录，按最新时间倒序：时间、来源 IP 及钱包地址。每次通过 POST /v1/session 签发会话时记录；历史自 2026-09-25 开始记录。

其他成员的登录记录不会在此展示以保护隐私安全。仅限控制台会话，需具备 viewer 或更高角色。

响应

响应字段

来自规范的 200 响应示例（示意数值）：

{
  "data": [
    {
      "signed_in_at": "2026-09-25T09:41:12.000Z",
      "ip": "203.0.113.10",
      "address": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE"
    }
  ]
}