Base Account / Integration

账号系统接入文档

按能力模块拆分的接入规范,供产品工程和 AI Agent 按需获取。

Issuerhttps://user.stringzhao.lifeAudiencebase-account-clientJWKShttps://user.stringzhao.life/.well-known/jwks.jsonDocv2026-03-06.3

Invitation Codes

仅复制邀请码文档

邀请码系统允许已登录用户为指定应用生成一次性邀请码(每用户每应用默认 3 个)。 兑换后系统记录邀请关系(谁邀请了谁),下游服务可据此做增长分析和奖励机制。

推荐使用 CLI 管理邀请码:npm install -g @stringzhao/base-account-cli。 注册服务:ba admin services create --origin <url>, 生成邀请码:ba invitation-codes generate -s <serviceKey>。 兑换邀请码仅需 code,无需 serviceKey。

接入步骤

  1. 生成邀请码

    已登录用户调用 POST /api/auth/invitation-codes/generate,传入 serviceKey,获得 8 位邀请码。每用户每应用默认可生成 3 个(管理员配额为 1000)。serviceKey 需先通过 CLI 注册服务:ba admin services create --origin https://your-app.example.com。

  2. 分享邀请码

    将邀请码通过任意渠道(聊天、邮件、社交媒体等)发送给受邀人。

  3. 受邀人兑换

    受邀人登录后调用 POST /api/auth/invitation-codes/redeem,仅需传入 code(不需要 serviceKey)。系统自动从邀请码记录中读取 serviceKey,记录邀请关系并返回 serviceKey 和邀请者 ID。

  4. 下游业务处理

    下游服务根据 redeem 返回的 serviceKey + creatorId 决定后续动作(如:解锁功能、发放奖励、建立推荐关系等)。

API 端点

POST/api/auth/invitation-codes/generate

为当前用户在指定应用下生成一个一次性邀请码。每用户每应用有配额限制(普通用户默认 3,管理员 1000)。serviceKey 需先通过 CLI 注册:ba admin services create --origin <url>。

Auth: access_token

展开查看请求/响应示例

Request

{
  "serviceKey": "my-app"
}

Response

{
  "success": true,
  "invitationCode": {
    "id": "clxxx...",
    "code": "ABCD1234",
    "serviceKey": "my-app",
    "status": "ACTIVE",
    "redeemedBy": null,
    "redeemedAt": null,
    "createdAt": "2026-03-06T10:00:00.000Z"
  }
}

Errors

  • 401 missing_access_token
  • 400 invalid_input
  • 400 invalid_service
  • 403 invitation_quota_exceeded
POST/api/auth/invitation-codes/redeem

兑换邀请码。仅需传入 code,无需 serviceKey(系统自动从邀请码记录中读取)。一次性使用,兑换后记录邀请关系(谁邀请了谁)。普通用户不能兑换自己生成的邀请码;管理员账号可用于自助开通。服务代理模式:使用 API key 认证时可传入 userId 代表终端用户兑换,适用于下游服务有独立 session 的场景。

Auth: access_token

展开查看请求/响应示例

Request

{
  "code": "ABCD1234",
  "userId": "usr_xxx"  // 可选,仅 API key 认证时生效,代表终端用户
}

Response

{
  "success": true,
  "serviceKey": "my-app",
  "creatorId": "usr_xxx"
}

Errors

  • 401 missing_access_token
  • 400 invalid_invitation_code
  • 400 self_redeem_not_allowed
  • 409 invitation_code_already_redeemed
POST/api/auth/invitation-codes/validate

仅校验邀请码有效性,不消费。仅需传入 code,无需 serviceKey。适用于前端实时校验场景。

Auth: access_token

展开查看请求/响应示例

Request

{
  "code": "ABCD1234"
}

Response

{
  "valid": true,
  "serviceKey": "my-app",
  "creatorId": "usr_xxx"
}

Errors

  • 401 missing_access_token
  • 400 invalid_input
GET/api/auth/invitation-codes?serviceKey=my-app

列出当前用户在指定应用下生成的所有邀请码及配额信息。

Auth: access_token

展开查看请求/响应示例

Response

{
  "codes": [
    {
      "id": "clxxx...",
      "code": "ABCD1234",
      "serviceKey": "my-app",
      "status": "REDEEMED",
      "redeemedBy": "usr_yyy",
      "redeemedAt": "2026-03-06T12:00:00.000Z",
      "createdAt": "2026-03-06T10:00:00.000Z"
    }
  ],
  "quota": { "used": 1, "total": 3 }
}

Errors

  • 401 missing_access_token
  • 400 invalid_input
POST/api/auth/invitation-codes/revoke

撤销自己生成的 ACTIVE 状态邀请码。已兑换的码不可撤销。

Auth: access_token

展开查看请求/响应示例

Request

{
  "codeId": "clxxx..."
}

Response

{
  "success": true
}

Errors

  • 401 missing_access_token
  • 404 invitation_code_not_found
  • 403 forbidden
  • 400 invalid_invitation_code

集成模板

邀请码接入流程

Browser / Web App
展开查看模板代码
const BASE = "https://user.stringzhao.life";
// SERVICE_KEY 需先通过 CLI 注册服务获得:
//   npm install -g @stringzhao/base-account-cli
//   ba admin services create --origin https://your-app.example.com
// 注册后会返回 serviceKey(格式:svc-xxx)
const SERVICE_KEY = "my-app";

// 1) 生成邀请码(邀请者操作)
const genRes = await fetch(BASE + "/api/auth/invitation-codes/generate", {
  method: "POST",
  headers: { "content-type": "application/json" },
  body: JSON.stringify({ serviceKey: SERVICE_KEY }),
  credentials: "include"
}).then((r) => r.json());

console.log("邀请码:", genRes.invitationCode.code); // e.g. "ABCD1234"

// 2) 校验邀请码(受邀人输入时实时校验)
const valRes = await fetch(BASE + "/api/auth/invitation-codes/validate", {
  method: "POST",
  headers: { "content-type": "application/json" },
  body: JSON.stringify({ code: "ABCD1234" }),
  credentials: "include"
}).then((r) => r.json());

if (!valRes.valid) {
  console.error("邀请码无效");
}

// 3) 兑换邀请码(受邀人确认后)
const redeemRes = await fetch(BASE + "/api/auth/invitation-codes/redeem", {
  method: "POST",
  headers: { "content-type": "application/json" },
  body: JSON.stringify({ code: "ABCD1234" }),
  credentials: "include"
}).then((r) => r.json());

console.log("邀请者:", redeemRes.creatorId);

// 4) 查看我的邀请码和配额
const listRes = await fetch(
  BASE + "/api/auth/invitation-codes?serviceKey=" + SERVICE_KEY,
  { credentials: "include" }
).then((r) => r.json());

console.log("已用/总配额:", listRes.quota.used, "/", listRes.quota.total);