POST/api/auth/sso/exchange

آخرین گام ورود SSO (SAML/OIDC): کد یکبارمصرف صادرشده توسط Callback را با یک Session-JWT معمولی مبادله میکند.

صفحه "POST /api/auth/sso/exchange — مرجع API" به بخش عملکردی مشخص شده در URL اشاره دارد. محتوای موجود با جزئیات مربوط به جریان واقعی، پیش‌نیازها و محدودیت‌های شناخته شده تکمیل می‌شود. Zentor سیستم کلید API برای توسعه‌دهندگان ندارد. برای داشبورد، از توکن‌های JWT با طول عمر ۱۲ ساعت و توکن‌های Refresh با طول عمر ۷ روز استفاده می‌شود. TOTP و SSO اختیاری هستند. توکن‌های Embed برای ویجت‌ها یک‌بار به صورت متن ساده نمایش داده می‌شوند و به دامنه‌های مجاز محدود می‌شوند. مستندات مربوط به `POST /api/auth/sso/exchange` باید به عنوان یک توصیف فنی دقیق از این نقطه پایانی خاص در نظر گرفته شود. موارد مهم شامل روش، مسیر، احراز هویت، فیلدهای اجباری، خطاهای احتمالی و این است که آیا فراخوانی مجدد همان اثر را ایجاد می‌کند یا خیر. این بخش راهنما، که آدرس آن `https://zentor-app.de/hilfe/api-referenz/auth/auth.sso_exchange` است، نباید شامل ادعاهای تبلیغاتی کلی باشد، بلکه فقط باید شامل مراحل یکپارچه‌سازی قابل اجرا و نمونه‌های پاسخ معتبر باشد. برای فراخوانی `/api/auth/sso/exchange`، درخواست باید مطابق با رجیستری ایجاد شود. مسیرهای عمومی نیازی به کلید API عمومی برای توسعه‌دهندگان ندارند، زیرا Zentor چنین سیستمی را ارائه نمی‌دهد. در مقابل، مسیرهای ویجت محافظت‌شده از توکن Embed که یک‌بار نمایش داده می‌شود و همچنین بررسی دامنه استفاده می‌کنند. وضعیت HTTP و محتوای JSON باید به طور مشترک ارزیابی شوند؛ یک فیلد `ok` به تنهایی جایگزین مدیریت خطا نمی‌شود. هنگام آزمایش `POST /api/auth/sso/exchange`، باید از مقادیر ناشناس استفاده شود. داده‌های واقعی مشتری، UUIDهای فعال، توکن‌های نشست و مهر زمانی‌های خاص نباید در نمونه‌های عمومی قرار گیرند. محدودیت کلی پلتفرمی شناخته شده، ۲۰۰۰ درخواست در ۱۵ دقیقه است؛ محدودیت انفرادی متفاوتی مشخص نشده است. فراخوانی‌های POST غیر-ایدم‌پوت نباید پس از قطع ارتباط شبکه نامشخص، به طور کورکورانه تکرار شوند. خطاهای یکپارچه‌سازی معمول برای این مسیر، ناشی از عدم وجود پارامترهای اجباری، انواع داده نادرست، کدهای یک‌بار مصرف منقضی شده، دامنه‌های غیرمجاز یا عدم پیاده‌سازی یک مجموعه داده است. برنامه باید این موارد را به طور جداگانه مدیریت کند و پیام خطایی را که از نقطه پایانی دریافت می‌شود، ثبت کند، بدون اینکه محتوای حساس را ثبت کند. یک درخواست موفق فقط این مرحله پردازش را تأیید می‌کند، نه به طور خودکار موفقیت یک عملیات بعدی مانند ایمیل، پرداخت یا SSO. این موضوع برای "POST /api/auth/sso/exchange" کاملاً مرتبط است. بررسی فنی این صفحه باید به طور اجباری بر اساس رجیستری موجود در `app/frontend/src/content/api-reference/` و مسیرهای بک‌اند مربوطه انجام شود. یادداشت‌های تست زنده فقط باید ادعاهایی را مطرح کنند که واقعاً بررسی شده‌اند. یک تست منفی یا یک آنالیز کد، مدرک کاملی از موفقیت نیست. بنابراین، برای POST /api/auth/sso/exchange — مرجع API، باید تمایز روشنی بین ساختار مستند شده، تست خودکار و رفتار زنده قابل مشاهده وجود داشته باشد.

{"code":"<کد یکبارمصرف از SSO-Callback-Redirect>"}

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