Autentifikatsiya
Email proof, register, login va tenantga bog‘langan JWT.
Register ketma-ketligi
POST /api/v1/auth/magic-link/requestga{ "email": "owner@example.uz" }yuboring.- Emaildagi registration proof’ni oling.
POST /api/v1/auth/registerga quyidagi body’ni yuboring.
{
"token": "YOUR_EMAIL_PROOF",
"email": "owner@example.uz",
"password": "YOUR_NEW_PASSWORD",
"confirmPassword": "YOUR_NEW_PASSWORD",
"company": { "name": "Example MCHJ", "taxId": "123456789" }
}Parol kamida 15 Unicode belgi va ko‘pi bilan 72 UTF-8 bayt. company ixtiyoriy; STIR berilsa 9 raqam bo‘lishi kerak. Muvaffaqiyatli register 201 va token juftligini qaytaradi.
202 — email yetkazilgan degani emas
Magic-link request javobi account mavjudligini yoki inbox delivery’ni oshkor qilmaydi. Email provider sozlanmagan, so‘rov cheklangan yoki email yetib bormagan bo‘lishi mumkin. Yangi proof so‘rash kerak bo‘lishi mumkin; mavjud identity paroli register orqali almashtirilmaydi.
Login va 2FA
POST /api/v1/auth/login email va parolni tekshiradi. 200 token juftligini beradi; 202 ikkinchi faktor kerakligini bildiradi va token bermaydi. Tokenni bypass qilish uchun host/headerlarni almashtirmang.
Email 2FA
Email 2FA yoqilgan account uchun email/parol bilan boshlangan login 202 va quyidagi shakldagi javobni qaytaradi. challengeId va expiresAt qiymatlari har bir challenge uchun serverdan olinadi:
{
"challengeId": "123e4567-e89b-12d3-a456-426614174000",
"expiresAt": "2026-01-01T12:05:00Z",
"channel": "EMAIL"
}O‘sha POST /api/v1/auth/loginga email, parol, javobdagi challengeId va emailga kelgan 8 raqamli code yuboring:
{
"email": "owner@example.uz",
"password": "YOUR_TEST_ACCOUNT_PASSWORD",
"challengeId": "123e4567-e89b-12d3-a456-426614174000",
"code": "12345678"
}Kod 5 daqiqada eskiradi va 5 ta taxminga ruxsat beradi. 202 email inbox’ga yetib kelganini kafolatlamaydi; kod provider tomonidan qabul qilingan bo‘lishi kerak. 429 bo‘lsa Retry-Afterga amal qiling.
Authenticator (TOTP): server versiyasini tekshiring
OpenAPI snapshot va deploy qilingan backend farqi
API Reference repodagi backenddan generatsiya qilingan snapshotni ko‘rsatadi; unda totpCode, recoveryCode va Authenticator endpointlari bor. Bu production ham shu versiyada degani emas: serverga mos backend deploy qilinganini operator bilan tekshiring. Backend deploy’dan keyin snapshotni Swagger refresh orqali yangilang; maydonlarni qo‘lda yozmang.
TOTP yoqilgan account uchun birinchi login 202 channel=TOTP qaytaradi; email yuborilmaydi va email challenge maydonlari null bo‘ladi:
{ "challengeId": null, "expiresAt": null, "channel": "TOTP" }Email va parol bilan login’ni 6 raqamli totpCode bilan takrorlang:
{
"email": "owner@example.uz",
"password": "YOUR_TEST_ACCOUNT_PASSWORD",
"totpCode": "123456"
}Authenticatorga kira olmasangiz, uning o‘rniga bitta ishlatilmagan recovery code yuboring:
{
"email": "owner@example.uz",
"password": "YOUR_TEST_ACCOUNT_PASSWORD",
"recoveryCode": "ABCD-EFGH-JKLM-NPQR"
}totpCode va recoveryCodeni birga yoki email challengeId/code bilan aralashtirmang; email maydonlari juft bo‘lishi kerak. Aralash faktorlar yoki noto‘liq email juftligi 400 qaytaradi. TOTP bir marta ishlatiladi: enrollmentdan keyin keyingi 30 soniyalik kodni kuting. Faktor urinishlari 5 daqiqada 5 marta bilan cheklangan; 429da Retry-Afterga amal qiling.
Bearer token
Authorization: Bearer YOUR_ACCESS_TOKENHar bir token imzolangan tenant_id bilan aynan bitta tenant nomidan ishlaydi. Boshqa tenant subdomainida ishlatish rad etiladi. Central API host faol membership’ni tekshiradi; tenantni o‘zboshimchalik bilan header orqali tanlab bo‘lmaydi.
Refresh va logout
Backend API uchun refresh body:
{ "refreshToken": "YOUR_REFRESH_TOKEN" }POST /api/v1/auth/refresh:200va yangi token juftligi. Eski refresh token qayta ishlatilsa token family revoke qilinadi.POST /api/v1/auth/logout: backend kontraktidagi refresh token bilan sessionni tugatish; muvaffaqiyat204.- Refresh’ning network/
5xxnatijasi noma’lum bo‘lsa eski token bilan avtomatik takrorlamang; qayta login qiling.
Browser frontend bilan farq
Backend login 200 javobida accessToken va refreshTokenni JSON body’da qaytaradi; HttpOnly cookie o‘rnatmaydi va sahifaga redirect qilmaydi. Mavjud Next.js frontend BFF tokenlarni HttpOnly cookie’da saqlaydi va frontend muvaffaqiyatli kirishda kerakli sahifaga yo‘naltiradi; browser refresh/logout body yubormaydi. Bu qoida bevosita backend API client uchun emas. JWT/refresh tokenlarni localStorage, URL, loglar yoki docs saytiga qo‘ymang.