POST/api/auth/sso/exchange
Bước cuối cùng của đăng nhập SSO (SAML/OIDC): đổi mã dùng một lần từ chuyển hướng thành access token và refresh token.
Sau khi đăng nhập hoàn tất tại identity provider, Zentor App chuyển hướng trình duyệt trở lại kèm mã dùng một lần trong tham số truy vấn `sso_code`. Hãy gửi mã này trong trường `code`. Phản hồi chứa `token` và `refreshToken`, giống như đăng nhập thông thường. Mỗi mã chỉ có hiệu lực một lần và trong thời gian ngắn. Mã đã được sử dụng, đã hết hạn hoặc không hợp lệ sẽ trả về 400 `SSO_EXCHANGE_INVALID`; khi đó người dùng phải bắt đầu lại đăng nhập SSO. Do đó, lệnh gọi này không có tính idempotent.
Tổng quan
Lệnh gọi: POST /api/auth/sso/exchange. Endpoint này thuộc nhóm “Xác thực” trong API của Zentor App. Endpoint này được truy cập công khai và không yêu cầu xác thực. Lệnh gọi không có tính idempotent: mỗi lệnh gọi thành công đều kích hoạt lại hành động. Tham số bắt buộc: code (body). Các trường hợp lỗi được tài liệu hóa: 400 SSO_EXCHANGE_INVALID. Phản hồi mẫu bên dưới cho thấy cấu trúc của một phản hồi thành công ở định dạng JSON.
Xác thực & bảo mật
Không cần xác thực
Lũy đẳng (idempotent): Không
Tham số
code(body, string, bắt buộc)— Mã dùng một lần từ chuyển hướng SSORequest mẫu
{"code":"<Mã dùng một lần từ SSO-Callback-Redirect>"}Response mẫu
{"ok":true,"token":"<JWT>","refreshToken":"<Refresh-Token>"}Mã lỗi
400 SSO_EXCHANGE_INVALID — Mã không hợp lệ, đã được sử dụng hoặc đã hết hạn.Hành vi đã được xác minh
Mã không hợp lệ trả về 400 `SSO_EXCHANGE_INVALID`. Trường hợp thành công yêu cầu đăng nhập hoàn chỉnh tại identity provider đã được cấu hình.
Xác thực
POST /api/auth/loginXác thực người dùng bằng địa chỉ email hoặc tên người dùng cùng mật khẩu, và cấp một access token (JWT) cùng một refresh token.POST /api/auth/refreshĐổi một refresh token hợp lệ thành một cặp access token và refresh token mới.POST /api/auth/forgot-passwordBắt đầu quá trình đặt lại mật khẩu: nếu có tài khoản với địa chỉ email đã cho, tài khoản đó sẽ nhận được email chứa liên kết đặt lại.POST /api/auth/reset-passwordĐặt mật khẩu mới bằng reset token từ email đặt lại mật khẩu.