交互 API

交互接口供登录页面使用，处理用户的认证交互流程，包括登录、注册、验证码收发和忘记密码等操作。

注意： 交互接口无需管理员令牌认证，由登录前端直接调用。

获取登录体验配置

`GET /api/interaction/sign-in-experience`

获取登录页面所需的登录体验配置，包括品牌信息、登录方式、注册方式、密码策略等。登录前端在加载时调用此接口以渲染登录页面。

请求示例：

bash

curl -X GET https://your-domain/api/interaction/sign-in-experience

成功响应：

json

{
  "code": 0,
  "message": "success",
  "result": {
    "branding": {
      "logo_url": "https://example.com/logo.png",
      "dark_logo_url": "https://example.com/logo-dark.png",
      "favicon": "https://example.com/favicon.ico",
      "primary_color": "#4F46E5",
      "dark_primary_color": "#6366F1"
    },
    "sign_in": {
      "methods": [
        {
          "identifier": "username",
          "password": true,
          "verification_code": false
        },
        {
          "identifier": "email",
          "password": true,
          "verification_code": true
        }
      ]
    },
    "sign_up": {
      "identifiers": ["username"],
      "password": true,
      "verify": false
    },
    "password_policy": {
      "min_length": 8,
      "require_lowercase": true,
      "require_uppercase": false,
      "require_numbers": true,
      "require_special_chars": false
    },
    "social_connectors": [
      {
        "connector_id": "github",
        "name": "GitHub",
        "type": "Social"
      }
    ],
    "terms_of_use_url": "https://example.com/terms",
    "privacy_policy_url": "https://example.com/privacy"
  }
}

用户登录

`POST /api/interaction/sign-in`

使用标识符（用户名/邮箱/手机号）和密码进行登录。

请求头：

Content-Type: application/json

请求体：

字段	类型	必填	说明
`identifier`	string	是	登录标识符（用户名、邮箱或手机号）
`password`	string	是	用户密码

请求示例：

bash

curl -X POST https://your-domain/api/interaction/sign-in \
  -H "Content-Type: application/json" \
  -d '{
    "identifier": "john_doe",
    "password": "secure123"
  }'

成功响应：

json

{
  "code": 0,
  "message": "success",
  "result": {
    "redirect_to": "https://app.example.com/callback?code=abc123&state=xyz"
  }
}

说明： 登录成功后返回重定向地址，前端应跳转到该地址完成 OIDC 授权流程。

错误响应（凭证无效）：

json

{
  "code": 401,
  "message": "用户名或密码错误",
  "result": ""
}

错误响应（用户被挂起）：

json

{
  "code": 403,
  "message": "用户账户已被挂起，请联系管理员",
  "result": ""
}

用户注册

`POST /api/interaction/register`

注册新用户。支持的注册方式取决于登录体验配置中的 sign_up 设置。

请求体：

字段	类型	必填	说明
`username`	string	条件必填	用户名（当注册标识符包含 `username` 时必填）
`email`	string	条件必填	邮箱（当注册标识符包含 `email` 时必填）
`password`	string	条件必填	密码（当登录体验要求密码时必填）

请求示例（用户名注册）：

bash

curl -X POST https://your-domain/api/interaction/register \
  -H "Content-Type: application/json" \
  -d '{
    "username": "new_user",
    "password": "myPassword123"
  }'

请求示例（邮箱注册）：

bash

curl -X POST https://your-domain/api/interaction/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "newuser@example.com",
    "password": "myPassword123"
  }'

成功响应：

json

{
  "code": 0,
  "message": "success",
  "result": {
    "redirect_to": "https://app.example.com/callback?code=def456&state=xyz"
  }
}

错误响应（用户名已存在）：

json

{
  "code": 400,
  "message": "用户名已存在",
  "result": ""
}

错误响应（密码不符合策略）：

json

{
  "code": 400,
  "message": "密码不符合安全要求：长度至少8位，需包含小写字母和数字",
  "result": ""
}

发送验证码

`POST /api/interaction/verification-code`

发送验证码到指定的邮箱或手机号。验证码用于登录验证、注册验证或忘记密码流程。

请求体：

字段	类型	必填	说明
`identifier`	string	是	接收验证码的邮箱或手机号
`identifier_type`	string	是	标识符类型：`email` 或 `phone`
`interaction_type`	string	是	交互类型：`sign_in`、`register`、`forgot_password`

请求示例（登录验证码）：

bash

curl -X POST https://your-domain/api/interaction/verification-code \
  -H "Content-Type: application/json" \
  -d '{
    "identifier": "john@example.com",
    "identifier_type": "email",
    "interaction_type": "sign_in"
  }'

请求示例（忘记密码验证码）：

bash

curl -X POST https://your-domain/api/interaction/verification-code \
  -H "Content-Type: application/json" \
  -d '{
    "identifier": "13800138000",
    "identifier_type": "phone",
    "interaction_type": "forgot_password"
  }'

成功响应：

json

{
  "code": 0,
  "message": "success",
  "result": {
    "expires_in": 300
  }
}

响应字段说明：

字段	类型	说明
`expires_in`	integer	验证码有效期（秒），通常为 300（5 分钟）

错误响应（发送频率限制）：

json

{
  "code": 400,
  "message": "验证码发送过于频繁，请稍后重试",
  "result": ""
}

验证验证码

`POST /api/interaction/verify-code`

验证用户输入的验证码是否正确。

请求体：

字段	类型	必填	说明
`identifier`	string	是	接收验证码的邮箱或手机号
`identifier_type`	string	是	标识符类型：`email` 或 `phone`
`interaction_type`	string	是	交互类型：`sign_in`、`register`、`forgot_password`
`code`	string	是	用户输入的验证码

请求示例：

bash

curl -X POST https://your-domain/api/interaction/verify-code \
  -H "Content-Type: application/json" \
  -d '{
    "identifier": "john@example.com",
    "identifier_type": "email",
    "interaction_type": "sign_in",
    "code": "123456"
  }'

成功响应：

json

{
  "code": 0,
  "message": "success",
  "result": {
    "redirect_to": "https://app.example.com/callback?code=ghi789&state=xyz"
  }
}

错误响应（验证码错误）：

json

{
  "code": 400,
  "message": "验证码错误或已过期",
  "result": ""
}

忘记密码

`POST /api/interaction/forgot-password`

重置用户密码。调用此接口前需要先通过验证码验证身份。

请求体：

字段	类型	必填	说明
`identifier`	string	是	用户的邮箱或手机号（需与验证码验证时一致）
`new_password`	string	是	新密码（需符合密码策略）

请求示例：

bash

curl -X POST https://your-domain/api/interaction/forgot-password \
  -H "Content-Type: application/json" \
  -d '{
    "identifier": "john@example.com",
    "new_password": "newSecure456"
  }'

成功响应：

json

{
  "code": 0,
  "message": "success",
  "result": null
}

错误响应（未验证身份）：

json

{
  "code": 400,
  "message": "请先完成验证码验证",
  "result": ""
}

错误响应（密码不符合策略）：

json

{
  "code": 400,
  "message": "密码不符合安全要求：长度至少8位，需包含小写字母和数字",
  "result": ""
}

交互流程说明

密码登录流程

1. GET /api/interaction/sign-in-experience    -- 获取登录配置
2. POST /api/interaction/sign-in              -- 提交用户名和密码
3. 前端跳转到 redirect_to 地址                  -- 完成 OIDC 授权

验证码登录流程

1. GET /api/interaction/sign-in-experience    -- 获取登录配置
2. POST /api/interaction/verification-code    -- 发送验证码
3. POST /api/interaction/verify-code          -- 验证码校验并登录
4. 前端跳转到 redirect_to 地址                  -- 完成 OIDC 授权

用户名注册流程

1. GET /api/interaction/sign-in-experience    -- 获取注册配置
2. POST /api/interaction/register             -- 提交注册信息
3. 前端跳转到 redirect_to 地址                  -- 完成 OIDC 授权

忘记密码流程

1. POST /api/interaction/verification-code    -- 发送验证码（interaction_type: forgot_password）
2. POST /api/interaction/verify-code          -- 验证码校验
3. POST /api/interaction/forgot-password      -- 设置新密码
4. 引导用户重新登录

交互 API ​

获取登录体验配置 ​

GET /api/interaction/sign-in-experience ​

用户登录 ​

POST /api/interaction/sign-in ​

用户注册 ​

POST /api/interaction/register ​

发送验证码 ​

POST /api/interaction/verification-code ​

验证验证码 ​

POST /api/interaction/verify-code ​

忘记密码 ​

POST /api/interaction/forgot-password ​

交互流程说明 ​

密码登录流程 ​

验证码登录流程 ​

用户名注册流程 ​

忘记密码流程 ​

交互 API

获取登录体验配置

`GET /api/interaction/sign-in-experience`

用户登录

`POST /api/interaction/sign-in`

用户注册

`POST /api/interaction/register`

发送验证码

`POST /api/interaction/verification-code`

验证验证码

`POST /api/interaction/verify-code`

忘记密码

`POST /api/interaction/forgot-password`

交互流程说明

密码登录流程

验证码登录流程

用户名注册流程

忘记密码流程