Autentifikatsiya va ruxsatlar

Zanjir

integratsiya maxfiy kaliti ──> POST /v1/auth/login ──> access_token + refresh_token
                                                              │
                              POST /v2/auth/refresh <─────────┘  muddati tugaganda

Ushbu hujjatdagi metodlardan faqat shu ikkitasi tokensiz ishlaydi. Qolgan barcha so’rovlar quyidagi sarlavha bilan yuboriladi:

Authorization: Bearer <access_token>

Tokenlarning amal qilish muddati

Maxfiy kalit orqali kirishda muddatlar kodda belgilangan va kompaniya sozlamalariga bog’liq emas:

Token	Muddat	Loginga javobda
access_token	15 kun	expires_in: 1296000 (soniya)
refresh_token	30 kun	refresh_token maydoni bo’lib keladi; o’zining expires_ini yo’q

Yangilashdan keyin muddat o’zgarishi mumkin

Yangilash (POST /v2/auth/refresh) server konfiguratsiyasidan olingan muddatlarga ega juftlikni beradi. expires_in har safar javobdan o’qiladi.

Tokenni yangilash

curl -X POST 'https://api-admin.billz.ai/v2/auth/refresh' \
  -H 'Content-Type: application/json' \
  -H 'platform-id: 7d4a4c38-dd84-4902-b744-0488b80a4c01' \
  -d '{ "refresh_token": "..." }'

Javobda expires_in va refresh_expires_in maydonlariga ega yangi tokenlar juftligi keladi. Eski refresh-tokendan boshqa foydalanib bo’lmaydi.

Refresh-tokendan qayta foydalanish butun sessiyalar oilasini bekor qiladi

Atomar rotatsiya: bitta refresh-token faqat bir marta almashtiriladi. Agar allaqachon ishlatilgan token taqdim etilsa, server buni xavfsizlik buzilishi deb baholaydi va asl logindan kelib chiqqan butun sessiyalar oilasini bekor qiladi, — shundan so’ng faqat yangi POST /v1/auth/login. Bunday urinishga javob — 400, "error": "invalid_grant", "message": "token reuse detected".

Bitta refresh-token bilan 5 soniya ichidagi parallel yangilashlar bir xil yangi juftlikni oladi. Juftlik umumiy xotirada saqlanadi va bir joydan yangilanadi.

Yangilash xatolari 400 kodi bilan keladi (RFC 6749 §5.2): oddiy metoddagi 401 muddati o’tgan access-tokenni, yangilashdagi 400 esa yaroqsiz refresh-tokenni anglatadi. error maydonida standart kodi keladi: invalid_request, invalid_grant, unauthorized_client; ichki nosozlik — 500 bilan server_error.

Ruxsatlar

Kalit ruxsati ikkita mustaqil darajadan tashkil topgan.

1-daraja — marshrut. «HTTP-metod + marshrut andozasi» juftligi barcha kompaniyalar uchun bir xil bo’lgan qat’iy belgilangan marshrutlar ro’yxatidan topilishi lozim. To’liq ro’yxat — integratsiya kaliti nimalarga qodirligi.

2-daraja — rol ruxsati. Kalitning o’z roli bor. Uning ruxsat kalitlari ruxsat etilgan so’rov bajarilayotganda tekshiriladi va javobda nima qaytarilishini hamda operatsiya amalga oshish-oshmasligini hal qiladi: kalit roli ruxsatlari.

Marshrut andozasi (/v2/transfer/:id/add) va HTTP-fe’li taqqoslanadi: PUT qayd etilgan joyda PATCH o’tmaydi; ID qiymatlari tekshiruvga ta’sir qilmaydi.

Ruxsatlar 20 daqiqaga keshlanadi; rolning o’zgarishi keshni tozalaydi.

Javob kodlari nimani anglatadi

Xatolik tanasi odatda {"code": ..., "message": ..., "error": ..., "data": null} bo’ladi. Sababi message + error juftligi bo’yicha farqlanadi:

Kod	message / error	Nima bo’ldi?
401	token error	token o’qilmayapti: kesilgan, buzilgan, begona imzo
401	token expired / token has been expired	muddati tugagan — yangilash talab etiladi
401	unauthorized / refresh token used as access	Authorization ga refresh-token qo’yilgan
401	unauthorized / session not found, session revoked	sessiya yopilgan yoki bekor qilingan — yangi login kerak
401	unauthorized / mismatch platform-id with token info	platform-id token berilganiga mos emas
401	unauthorized / user is not active, user has been expired	kalit o’chirilgan yoki uning muddati tugagan
403	forbidden / access denied	marshrut kalit uchun ruxsat etilgan ro’yxatda yo’q
403	blocked / company is blocked	kompaniya butunlay bloklangan

Bu holatlar tahlili — 403 va 404.

401 holatida mijozning harakatlar tartibi: refresh-token yaroqli bo’lsa, juftlikni yangilash, aks holda maxfiy kalit orqali qayta kirish, so’ngra dastlabki so’rovni takrorlash.

platform-id tokenni yangilashdan tashqari hamma joyda ixtiyoriy

Amaliyot

• Maxfiy kalit himoyalangan omborda saqlanadi.
• access_token muddati tugashidan oldin yangilanadi.
• Yangilash bitta joydan amalga oshiriladi.
• Har bir integratsiya uchun alohida kalit yaratiladi.