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 do Callback cấp lấy một JWT phiên thông thường.

Trang “POST /api/auth/sso/exchange — Tài liệu tham khảo API” đề cập đến phạm vi chức năng được nêu trong URL. Nội dung hiện có được bổ sung thêm quy trình thực tế, các điều kiện tiên quyết và các giới hạn đã biết. Zentor không có hệ thống khóa API dành cho nhà phát triển. Đối với bảng điều khiển, Session-JWT có thời hạn mười hai giờ và Refresh-Token có thời hạn bảy ngày được sử dụng; TOTP và SSO là tùy chọn. Widget-Embed-Token chỉ được hiển thị một lần dưới dạng văn bản rõ và bị ràng buộc với các Origin được cho phép. Tài liệu về `POST /api/auth/sso/exchange` phải được đọc một cách ràng buộc như mô tả kỹ thuật của chính endpoint cụ thể này. Điều quyết định là phương thức, đường dẫn, xác thực, các trường bắt buộc, các lỗi có thể xảy ra và câu hỏi liệu một lần gọi lại có gây ra cùng một hiệu ứng hay không. Do đó, phần trợ giúp https://zentor-app.de/hilfe/api-referenz/auth/auth.sso_exchange này không được chứa các tuyên bố quảng cáo chung chung, mà chỉ gồm các bước tích hợp có thể tái hiện và các ví dụ phản hồi đã được kiểm chứng. Để gọi `/api/auth/sso/exchange`, yêu cầu được xây dựng theo Registry. Các route công khai không cần khóa API chung cho nhà phát triển, vì Zentor không cung cấp hệ thống khóa như vậy. Ngược lại, các route widget được bảo vệ sử dụng Embed-Token chỉ hiển thị một lần và kiểm tra Origin. Mã trạng thái HTTP và nội dung JSON phải được đánh giá cùng nhau; riêng trường `ok` không thay thế được việc xử lý lỗi. Khi kiểm thử `POST /api/auth/sso/exchange`, cần sử dụng các giá trị đã được ẩn danh. Dữ liệu khách hàng thực, UUID thật từ môi trường sản xuất, Session-Token và dấu thời gian cụ thể không được xuất hiện trong các ví dụ công khai. Giới hạn đã biết trên toàn nền tảng là 2.000 yêu cầu trong vòng 15 phút; không có bằng chứng về giới hạn riêng khác cho từng endpoint. Các lệnh gọi POST không idempotent không được lặp lại một cách mù quáng sau khi kết nối mạng bị gián đoạn không rõ ràng. Các lỗi tích hợp điển hình cho route này phát sinh do thiếu tham số bắt buộc, sai kiểu dữ liệu, mã dùng một lần đã hết hạn, Origin không được phép hoặc bản ghi dữ liệu chưa được triển khai. Ứng dụng nên xử lý riêng từng trường hợp như vậy và ghi nhật ký thông báo lỗi do endpoint trả về, mà không ghi lại nội dung bí mật. Một request thành công chỉ xác nhận bước xử lý này, chứ không tự động xác nhận sự thành công của email, thanh toán hoặc SSO diễn ra sau đó. Điều này liên quan trực tiếp đến “POST /api/auth/sso/exchange”. Việc kiểm tra kỹ thuật của trang này bắt buộc phải dựa trên Registry trong `app/frontend/src/content/api-reference/` và các route backend tương ứng. Các ghi chú kiểm thử trực tiếp chỉ được khẳng định những gì đã thực sự được kiểm tra. Một kiểm thử phủ định hoặc sự tương tự về mã không phải là bằng chứng thành công đầy đủ. Vì vậy, đối với POST /api/auth/sso/exchange — Tài liệu tham khảo API, cần phân biệt rõ giữa cấu trúc đã được tài liệu hóa, kiểm thử tự động và hành vi thực tế đã được quan sát một cách chắc chắn.

{"code":"<Mã dùng một lần từ SSO-Callback-Redirect>"}

{"ok":true,"token":"<JWT>","refreshToken":"<Refresh-Token>"}