# Autentifikatsiya va ruxsatlar

> Integratsiya kaliti, tokenlar, yangilash va ruxsatlar modeli.

## Zanjir

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

![Umumiy sxema: maxfiy kalit POST orqali bir juft tokenga almashtiriladi /v1/auth/login, so’rovlar … bilan yuboriladi access\_token, muddati tugaganda juftlik POST orqali yangilanadi /v2/auth/refresh, yangilash muvaffaqiyatsiz bo’lsa, maxfiy kalit orqali qayta kiriladi](/_astro/01-overview.DMuaIw_n_Z206cPN.webp)

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

```plaintext
Authorization: Bearer <access_token>
```

![Tokenli so’rov: Authorization Bearer sarlavhali GET access\_token, token yaroqli bo’lsa javob 200, muddati o’tgan bo’lsa 401 Token is expired](/_astro/02-use-token.xdjUXBrA_176idQ.webp)

## 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_in`i 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

```bash
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.

![Tokenlar juftligini yangilash: POST /v2/auth/refresh bilan refresh\_token, javobda yangi access\_token va refresh\_token, eski juftlik almashtiriladi](/_astro/04-refresh.D_WaiJyq_Z1T4GfQ.webp)

> **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](/uz/reference/permissions/).

**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](/uz/reference/role-permissions/).

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](/uz/troubleshooting/403-and-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.

![401 xatosini qayta ishlash: agar refresh\_token yaroqli bo’lsa, POST so’rovi /v2/auth/refresh, aks holda maxfiy kalit bilan qayta kirish, so’ngra dastlabki so’rovni takrorlash](/_astro/05-401.CUC4gMSF_1RHh.webp)

> **`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.