iam-service/docs/SCALAR_GUIDE.md

IAM Service — Scalar 调用顺序指南

Authentication（认证方式）

本服务使用 JWT Bearer Token：

• 登录成功后拿到 access_token
• 后续请求在 Header 中带：
  • Authorization: Bearer <access_token>
• 租户上下文：
  • 保护接口默认从 Token claim 的 tenant_id 推导租户
  • 可选兼容 X-Tenant-ID: <uuid>，若同时提供 Header 与 Token，则必须一致，否则返回 403

通用响应结构

成功响应：

{ "code": 0, "message": "Success|Created|Accepted", "data": {}, "trace_id": null }

错误响应（示例）：

{ "code": 20006, "message": "Missing authorization header", "details": null, "trace_id": null }

常见错误码（节选）：

• 20006：缺少必要 Header（如 Authorization）
• 20003：无权限（403）
• 20005：账号或密码错误
• 30000：请求参数错误（400）
• 30002：资源不存在（404）
• 30003：资源冲突（409）
• 40000：请求过于频繁（429）
• 10001：数据库错误（500）

Step-by-step（可复制流程）

Step 0：创建租户（可选）

POST /tenants/register

• Header：无
• Body：

{ "name": "Tenant A", "config": { "theme": { "primary": "#1d4ed8" } } }

成功（201）从 data.id 取出租户 ID：

{ "code": 0, "message": "Created", "data": { "id": "<tenant_id>", "name": "Tenant A", "status": "active", "config": {} }, "trace_id": null }

下一步依赖：tenant_id（用于注册/登录时的 X-Tenant-ID）。

Step 1：注册用户

POST /auth/register

• 必需 Header：X-Tenant-ID: <tenant_id>
• Body：

{ "email": "user@example.com", "password": "securePassword123" }

成功（201）从 data.id 取出 user_id（后续可用于用户管理接口）：

{ "code": 0, "message": "Created", "data": { "id": "<user_id>", "email": "user@example.com" }, "trace_id": null }

Step 2：登录获取访问令牌（Authentication 入口）

POST /auth/login

• 必需 Header：X-Tenant-ID: <tenant_id>
• Body：

{ "email": "user@example.com", "password": "securePassword123" }

成功（200）从 data.access_token 取出访问令牌：

{ "code": 0, "message": "Success", "data": { "access_token": "<jwt>", "refresh_token": "<opaque>", "token_type": "Bearer", "expires_in": 900 }, "trace_id": null }

下一步依赖：access_token。

Step 3：获取当前租户信息（Tenant）

GET /tenants/me

• 必需 Header：Authorization: Bearer <access_token>
• 可选 Header：X-Tenant-ID: <tenant_id>（如提供必须与 token tenant_id 一致）

成功（200）：

{ "code": 0, "message": "Success", "data": { "id": "<tenant_id>", "name": "Tenant A", "status": "active", "config": {} }, "trace_id": null }

Step 4：查看当前用户权限（Me）

GET /me/permissions

• 必需 Header：Authorization: Bearer <access_token>

成功（200）：

{ "code": 0, "message": "Success", "data": ["tenant:read","tenant:write"], "trace_id": null }

下一步依赖：确认具备目标权限（例如 user:read / role:read）。

Step 5：列出用户（User）

GET /users?page=1&page_size=20

• 必需 Header：Authorization: Bearer <access_token>
• 分页规则：
  • page 默认 1，必须 >= 1
  • page_size 默认 20，范围 1..=200

成功（200）：

{ "code": 0, "message": "Success", "data": [{ "id": "<user_id>", "email": "user@example.com" }], "trace_id": null }

Step 6：列出角色（Role）

GET /roles

• 必需 Header：Authorization: Bearer <access_token>

成功（200）：

{ "code": 0, "message": "Success", "data": [{ "id": "<role_id>", "name": "Admin", "description": "..." }], "trace_id": null }

限流说明（Auth）

• /auth/login：约 2 req/s，burst 10（同一 IP）
• /auth/register：约 1 req/s，burst 5（同一 IP）
• 触发后返回：HTTP 429 + code=40000