Hamkorlar uchun OAuth ilovalari

Hamkorga tegishli OAuth ilovasi bir nechta Planfix hisoblariga ulanadigan integratsiya uchun mo‘ljallangan. Bitta ilova credentiallari barcha mijoz hisoblarida ishlatiladi, biroq har bir hisob ruxsatni alohida nazorat qiladi va har bir foydalanuvchi o‘zining ulanishiga rozilik bildiradi.

Agar integratsiya faqat bitta hisob uchun mo‘ljallangan bo‘lsa, hisobga tegishli ilova yaratish osonroq.

Ilova yaratish

Hamkor hisobingizni oching.
OAuth applications bo‘limiga o‘ting.
Create application ni tanlang.
Foydalanuvchilar va administratorlar ko‘radigan nom va tavsifni kiriting.
OAuth client turini tanlang.
Redirect URI larni qo‘shing.
Minimal talab qilinadigan REST API scope larini tanlang.
Ilovani saqlang va uning credential larini nusxa oling.

Yangi ilova xususiy hisoblanadi va ulanish qilayotgan har bir hisobda aniq maʼqullashni talab qiladi.

OAuth client turi

Turi	Mo‘ljallangan ilovalar	Credential lar
Public	Mobil, ish stoli va brauzer ilovalari hamda mahalliy MCP mijozlari.	Faqat `client_id`. Client secret yo‘q; PKCE S256 majburiy.
Confidential	Sirni foydalanuvchi qurilmasidan tashqarida va client tomon kodida saqlash mumkin bo‘lgan server-tomon ilovalar.	`client_id` va `client_secret`.

OAuth client turi ilovaning nashr etilgani bilan bog‘liq emas. Masalan, xususiy mobil ilova client secret bo‘lmagan public OAuth client hisoblanadi.

Redirect URI lar

Planfix foydalanuvchini tizimga kirishdan keyin qaytarishi mumkin bo‘lgan har bir URL ni belgilang.

Veb-xizmat uchun https dan foydalaning.
http faqat localhost yoki 127.0.0.1 kabi loopback manzillar uchun ruxsat etilgan.
Loopback manzili uchun mijoz dinamik portdan foydalanishi mumkin, lekin sxema, host, path va query mos kelishi kerak.
Wildcardlar, URL fragmentlari yoki siz nazorat qilmaydigan redirect URI larni ishlatmang.

Scope lar

Scope lar ilovaning maksimal ruxsat darajasini belgilaydi. Faqat zarur kirish darajalarini so‘rang — qarang: REST API ruxsatlar ro'yxati.

Ilova scope lari foydalanuvchining odatiy huquqlarini almashtirmaydi. Hatto scope berilgan taqdirda ham, ilova faqat ushbu foydalanuvchiga mavjud bo‘lgan maʼlumotlar bilan ishlay oladi.

Redirect URI lar yoki scope larni o‘zgartirish yangi maʼqullash versiyasini yaratadi. Oldin ulangan hisoblar yangi versiyani ko‘rib chiqib maʼqullashi va foydalanuvchilar yana ulanib chiqishi kerak bo‘ladi.

Mijoz hisobini ulash

Xususiy hamkor ilovasi har bir hisobda administrator tomonidan aniq maʼqullashni talab qiladi.

Hamkor hisobingizdagi ilovani oching.
Maʼqullash havolasi sohasiga mijoz hisobining nomini kiriting.
Hosil bo‘lgan havolani nusxa ko‘chiring va ushbu hisobning administratoriga yuboring.
Administratordan egasini, redirect URI larni va scope larni tekshirib, ilovani maʼqullashni so‘rang.
Maʼqullashdan so‘ng, hisobdagi foydalanuvchilar OAuth avtorizatsiyasini tugallashlari mumkin. Har bir foydalanuvchi alohida o‘z nomidan rozilik beradi.

Havola Account management → API → OAuth and MCP applications sahifasini ochadi va so‘ralgan ilovani ko‘rsatadi.

Administrator o‘zi ham ilovani ulayotgan bo‘lsa, Approve and connect ni tanlashi mumkin.

Xususiy va nashr etilgan ilovalar

Holat	Hisobga qanday kiritiladi
Private	Har bir hisob administratoridan har doim aniq maʼqullashni talab qiladi.
Published	Hisob siyosati Allow published applications bo‘lsa, alohida maʼqullash talab etilmaydi. Agar siyosat Approved applications only bo‘lsa, u holda ham maʼqullash talab etiladi.

Nashr etish alohida Planfix tekshiruvidir. Ilovani yuborishdan oldin aniq nom va tavsif, minimal scope to‘plami, ishlaydigan redirect URI lar va integratsiyani ulash hamda o‘chirish bo‘yicha foydalanuvchi hujjatlarini tayyorlang. Nashr etish tartibi uchun Planfix Support bilan bog‘laning.

Ulanish manzillari

Global OAuth endpoint laridan foydalaning:

Maqsad	Manzil
Authorization	`https://auth.planfix.com/oauth/authorize`
Token	`https://auth.planfix.com/oauth/token`
Userinfo	`https://auth.planfix.com/oauth/userinfo`
MCP	`https://mcp.planfix.com/mcp`

Global URL ga hisob nomini qo‘shmang. Foydalanuvchi hisobni Planfix sahifasida tanlaydi. To‘liq protokol, jumladan resource, PKCE, tokenni yangilash va bekor qilish haqida Ilovalar uchun OAuth 2.0 da bayon etilgan.

Ilovani boshqarish

Hamkor quyidagilarni amalga oshirishi mumkin:

nom va tavsifni tahrirlash;
redirect URI lar va scope larni o‘zgartirish;
ilovani o‘chirish va qayta yoqish;
confidential ilovaning client secret ini aylantirish;
maʼlum bir hisob uchun ilova maʼqullash havolasini yaratish.

Secret aylantirilgandan so‘ng, eski client secret darhol ishlamay qoladi. Secret ni integratsiya serverida yangilang va uni hech qachon foydalanuvchilarga yubormang.

Ilovani o‘chirish barcha hisoblardagi OAuth avtorizatsiyasini va berilgan tokenlarni bloklaydi. Bu amal ilovadan foydalanuvchi bo‘lgan barcha mijozlarga taʼsir ko‘rsatadi.

Ishga tushirishdan oldingi tavsiyalar

Authorization Code with PKCE S256 dan foydalaning va state ni tekshiring.
Faqat kerakli scope larni so‘rang.
Tizimga kirgandan keyin foydalanuvchiga tanlangan hisobni ko‘rsating.
Refresh token aylanishini (rotation) qo‘llab-quvvatlang: muvaffaqiyatli refreshdan so‘ng oldingi refresh token yaroqsiz bo‘ladi.
Tokenlarni, authorization code larni, code_verifier ni yoki client secret larni loglarga yozmang.
Foydalanuvchilar qanday qilib integratsiyani uzib qo‘yishi va o‘z maʼlumotlarini o‘chirib yuborishni so‘rashi haqida hujjat tayyorlang.
Maʼqullash bekor qilinishi, ilovaning o‘chirilishi va qayta ulash senariylarini sinab ko‘ring.