Aegis Open API

应用接入

接入方的全部接口都在 /api/v1/apps/{appKey} 下，覆盖注册、登录、令牌刷新与用户资料。标准档下一次 fetch 即可完成登录；提高安全等级后路径与 JSON 结构不变，只是请求多一层包装。

App Key

向应用管理员索取。填入后本页示例会替换成你的值，并按该应用的实际配置展示。

接口文档

01调用示例

响应统一是 { code, message, data } 信封，code 为 200 表示成功。登录成功后 data 中包含 accessToken、refreshToken 与 expiresAt。

示例中只有登录会随安全等级变化。注册、短信、第三方和会话共用同一套包装，因此统一按标准档展示，换档时复用登录示例里的包装函数。

在 HTTPS 上直接发送 JSON，不涉及密钥与密码学库。

cURL

curl -X POST "/api/v1/apps/your_app_key/auth/login" \
  -H "Content-Type: application/json" \
  -d '{"account":"alice","password":"secret"}'

02应用配置

/config 是客户端唯一需要预先拉取的接口，在任何安全等级下都可以明文读取，响应可缓存 60 秒。它描述了这个应用的登录方式、验证码要求、注册字段、可用的第三方渠道，以及当前等级所需的全部参数。

GET /config 响应片段

JSON

{
  "protocolVersion": "aegis-app-v1",
  "app": { "key": "your_app_key", "name": "示例应用", "status": true },
  "auth": {
    "identifiers": ["username", "email", "phone"],
    "loginMethods": ["password", "sms", "oauth"],
    "registerMethods": ["password", "sms"],
    "registrationSchema": [
      { "name": "account",  "type": "text",     "required": true,  "mutable": false, "label": "账号" },
      { "name": "password", "type": "password", "required": true,  "mutable": true,  "label": "密码" },
      { "name": "nickname", "type": "text",     "required": false, "mutable": true,  "label": "昵称" }
    ],
    "captcha": { "login": true, "register": false, "sms": true },
    "autoLoginAfterRegister": true,
    "registerEnabled": true,
    "loginEnabled": true,
    "oauthProviders": [
      { "provider": "wechat", "displayName": "微信", "allowLogin": true, "sortOrder": 1 }
    ]
  },
  "security": { "level": "standard", "appKeyHeader": "X-Aegis-App-Key" },
  "endpoints": {
    "login": "/api/v1/apps/your_app_key/auth/login",
    "smsCode": "/api/v1/apps/your_app_key/auth/sms/code",
    "oauthUrl": "/api/v1/apps/your_app_key/auth/oauth/url",
    "me": "/api/v1/apps/your_app_key/me"
  }
}

注册表单按 registrationSchema 渲染，第三方登录按钮按 oauthProviders 渲染。管理员调整配置后客户端无需发版。endpoints 给出完整相对路径，客户端不需要自行拼接 appKey。

03安全等级

等级由应用管理员设定，客户端从 /config 读取。三档共用同一批路径和同一套请求响应结构，升档时只替换发送请求的那一层。

标准standard

HTTPS 上直接发 JSON，不涉及密钥和密码学库。

签名signed

每个请求附带一个 HMAC-SHA256 头，防篡改与重放。

加密sealed

在签名基础上再用 X25519 + XChaCha20-Poly1305 加密载荷。

签名档的待签名字符串按下列顺序拼接，字段之间用换行分隔，末尾不带换行。加密档在签名之外再加密载荷，两层同时生效：AEAD 保证密文未被篡改，而服务端公钥是公开的，任何人都能构造出合法密文，签名用来证明调用方持有 appSecret。

待签名字符串

说明

aegis-hmac-sha256
{appKey}
{大写 HTTP 方法}
{请求路径，不含 query}
{Unix 秒级时间戳}
{随机 nonce，8-128 字符}
{sha256Hex(请求体原始字节)}

完整实现见上方「调用示例 → 登录」中对应等级的代码。

appSecret 只能保存在你自己的服务端。移动端与前端场景请使用标准档，安全性由 HTTPS 和服务端风控保证。另外第三方回跳 /auth/oauth/callback 由第三方平台重定向浏览器发起，客户端无法为它签名或加密，加密档下这一跳仍是明文。要求全链路加密时请改用原生 SDK 的 /auth/oauth/exchange。

04错误码

错误共用同一个响应信封，code 是业务码， HTTP 状态码只表达大类。标注为网关层的错误表示请求在进入业务逻辑之前就被拦下，原因在请求包装，与账号密码无关。

业务码	层	含义	处理
40071	网关	时间戳无效或已过期	客户端时钟与服务端的偏差需在 5 分钟内
40077	网关	加密载荷认证失败	检查 AAD 的七行拼接、HKDF 盐与 nonce
40174 / 40175	网关	签名格式无效或校验失败	核对待签名字符串的字段顺序与换行，确认使用的是当前 appSecret
40970	网关	nonce 已被使用	每个请求生成新的随机 nonce
42670	网关	应用要求加密载荷	该应用处于加密档，不接受明文 JSON
40370	业务	该认证方式未启用	由应用管理员在认证策略中勾选
40393	业务	第三方账号未绑定，且渠道未开放自动注册	引导用户先用已有账号登录，再绑定第三方
40394	业务	手机号未注册，且应用未开放短信注册	改用其他登录方式，或由管理员开启短信注册
40470	业务	应用不存在或已停用	核对 appKey 与应用状态

排查包装问题时，可以请应用管理员在控制台运行接入自检。服务端会按同一套规格实跑一遍，指出是签名、时间戳还是 AAD 出错。

05接口清单

下列路径都位于 /api/v1/apps/your_app_key 之下。

GET	/config	应用能力与安全等级规格，免包装可读
POST	/captcha	签发图形验证码
POST	/auth/sms/code	申请短信验证码，purpose 取 login 或 register
POST	/auth/register	注册，method 取 password 或 sms
POST	/auth/login	登录，method 取 password 或 sms
POST	/auth/refresh	刷新访问令牌
POST	/auth/logout	注销当前会话，需 Bearer
POST	/auth/2fa/verify	完成二次认证挑战
POST	/auth/oauth/url	取第三方授权地址
GET	/auth/oauth/callback	第三方授权回跳，免包装
POST	/auth/oauth/exchange	原生 SDK 用 profile 换会话
GET	/me	当前登录用户资料，需 Bearer

用户资料、存储、积分等业务接口见完整接口文档。