Tham chiếu API — Verification

Resource: `verifiers`

`verifiers:listByUser`

Liệt kê verifiers mà user hiện tại đã liên kết.

Quyền: loggedIn

Response:

json

{
  "data": [
    {
      "name": "sms-otp-aliyun",
      "title": "SMS Verification",
      "verificationType": "sms-otp",
      "boundInfo": { "phone": "****1234" }
    }
  ]
}

`verifiers:listForVerify`

Liệt kê verifiers khả dụng để xác minh (bao gồm cả verifiers chưa liên kết).

Quyền: loggedIn

`verifiers:bind`

Liên kết verifier mới với tài khoản user.

Quyền: loggedIn

Request body:

json

{
  "verifier": "sms-otp-aliyun",
  "phone": "+84912345678"
}

Khi bindingRequired: true, user cần xác minh qua OTP trước khi liên kết hoàn tất.

`verifiers:unbind`

Xóa liên kết verifier.

Quyền: loggedIn + xác minh qua scene unbind-verifier

Request body:

json

{
  "verifier": "sms-otp-aliyun"
}

Resource: `smsOTP`

`smsOTP:create`

Tạo và gửi mã OTP qua SMS.

Quyền: loggedIn

Request body:

json

{
  "phone": "+84912345678"
}

`smsOTP:publicCreate`

Tạo SMS OTP không cần đăng nhập — dùng cho luồng đăng ký hoặc quên mật khẩu.

Quyền: public

VerificationManager API

`registerVerificationType(name, config)`

Đăng ký loại verification mới.

typescript

verificationManager.registerVerificationType('email-otp', {
  title: tval('Email OTP'),
  description: tval('Mã xác minh qua email'),
  bindingRequired: false,
  verification: EmailOTPVerification,
});

Tham số	Kiểu	Mô tả
`title`	`string`	Tên hiển thị
`description`	`string`	Mô tả
`bindingRequired`	`boolean`	Có yêu cầu user liên kết trước không
`verification`	`class`	Class xử lý gửi/xác minh OTP

`registerScene(name, config)`

Đăng ký kịch bản xác minh.

typescript

verificationManager.registerScene('custom-action', {
  actions: {
    'myResource:sensitiveAction': {
      getUserIdFromCtx: (ctx) => ctx.state.currentUser?.id,
      async onVerifySuccess(ctx, userId) {
        // Xử lý sau khi xác minh thành công
      },
    },
  },
  getVerifiers: async () => ['sms-otp-aliyun'],
});

`addSceneRule(rule)`

Thêm quy tắc cho phép scene nào dùng verification type nào.

typescript

verificationManager.addSceneRule((scene, verificationType) => {
  return scene === 'my-scene' && verificationType === 'sms-otp';
});

`registerAction(actionName, config)`

Đăng ký action cần xác minh.

typescript

verificationManager.registerAction('verifiers:bind', {
  manual: true,
  getBoundInfoFromCtx: (ctx) => ctx.action.params.values || {},
});

Tham số	Mô tả
`manual`	`true` nếu user tự cung cấp thông tin liên kết
`getBoundInfoFromCtx`	Hàm lấy thông tin liên kết từ context

`middleware()`

Trả về middleware chặn action cần xác minh. Plugin tự động đăng ký middleware này vào dataSourceManager.

SMSOTPProviderManager API

`registerProvider(type, config)`

Đăng ký SMS provider mới.

typescript

smsOTPProviderManager.registerProvider('twilio', {
  title: tval('Twilio SMS'),
  provider: twilioProvider,
});

Error Codes

Mã lỗi	Mô tả
`VERIFICATION_EXPIRED`	Mã OTP đã hết hạn
`VERIFICATION_INVALID`	Mã OTP không đúng
`VERIFICATION_MAX_ATTEMPTS`	Vượt quá số lần thử tối đa
`VERIFICATION_COOLDOWN`	Cần chờ cooldown trước khi gửi lại
`VERIFICATION_PROVIDER_ERROR`	Lỗi từ SMS/email provider
`ALREADY_BOUND`	User đã liên kết verifier này rồi
`INVALID_VERIFIER`	Verifier không tồn tại