Public app və OAuth: başqa hesabların app-ı qoşması

Son yeniləmə: 11 noyabr 2026 · 8 dəq oxunur

Addımlar

1. 1

   Hazırlıq

   1. developer.clomni.ai-da «Yeni app» açın, növ olaraq «Public app» seçin. Növ sonra dəyişmir.
   2. Redirect URI-ləri yazın (ən çox 10): administrator razılıq verəndən sonra Clomni-nin onu qaytardığı ünvan. Ünvan hərfi-hərfinə uyğun gəlməlidir: sxem, host, port, yol, query. Ulduz, # və istifadəçi adı olmaz.
   3. Yalnız https qəbul olunur. http://localhost, http://127.0.0.1, http://[::1] yerli sınaq üçündür, istənilən portla işləyir, amma yalnız app Live olana qədər.
   4. Scope-ları review-a göndərin. Public app-da hər scope review-dan keçir.
   5. Serveriniz varsa client secret yaradın. Secret yoxdursa app public client sayılır və yalnız client_id və PKCE ilə işləyir (brauzer və mobil tətbiq üçün). Secret yaradılandan sonra token sorğusunda həmişə tələb olunur.
2. 2

   Administratoru authorize ünvanına göndərin

   App code_verifier (43-128 simvol) yaradır, ondan code_challenge = BASE64URL(SHA256(code_verifier)) hesablayır, təsadüfi state yaradır və ikisini sessiyada saxlayır. Sonra administratoru bu ünvana göndərir:

   https://my.clomni.co/oauth/developer/authorize?client_id=capp_xxx&redirect_uri=https%3A%2F%2Fapp.example.com%2Fclomni%2Fcallback&response_type=code&scope=contacts:read%20conversations:read&state=STATE&code_challenge=CODE_CHALLENGE&code_challenge_method=S256

   Hamısı məcburidir: client_id, redirect_uri, response_type=code, scope (app-ın istədiyi və rədd edilməmiş scope-lar), state (ən çox 500 simvol), code_challenge (43 simvol), code_challenge_method=S256. client_id tanınmırsa və ya redirect_uri uyğun deyilsə, Clomni yönləndirmir və səhvi öz səhifəsində göstərir. Qalan səhvlər redirect URI-yə ?error=...&state=... kimi qayıdır: invalid_request, invalid_scope, unsupported_response_type, access_denied (administrator imtina etdi).

3. 3

   Administrator razılıq verir

   Razılıq ekranında «{app} Clomni-yə qoşulmaq istəyir», «Developer: {şirkət}», «Workspace» seçimi və «App bunları edə biləcək» siyahısı görünür. Administrator «İcazə ver» və ya «İmtina» basır. Yalnız workspace administratoru app qoşa bilər. Sorğu 10 dəqiqə işləyir və bir dəfə istifadə olunur. Paneldə nə görünür: «Paneldə App-lar» məqaləsi.

4. 4

   Kodu tokenə dəyişin

   Clomni qaytarır: https://app.example.com/clomni/callback?code=...&state=.... Əvvəl state-i sessiyadakı ilə müqayisə edin. Kod 60 saniyə və bir dəfə işləyir, ikinci dəfə gəlsə birincidən verilmiş tokenlər də ləğv olunur.

   curl -X POST https://api.clomni.ai/v1/oauth/token \
     -u "$CLOMNI_CLIENT_ID:$CLOMNI_CLIENT_SECRET" \
     -d grant_type=authorization_code \
     -d code="$CODE" \
     -d redirect_uri="https://app.example.com/clomni/callback" \
     -d code_verifier="$CODE_VERIFIER"

   Public client -u əvəzinə gövdədə client_id göndərir. Cavabda access_token (clomni_at_, 1 saat), refresh_token (clomni_rt_, 90 gün), scope, workspace_id və installation_id olur. Tokenləri installation_id üzrə saxlayın: bir workspace bir quraşdırmadır.

5. 5

   Tokeni yeniləyin

   grant_type=refresh_token və refresh_token=... ilə eyni ünvana sorğu göndərin. Hər yeniləmədə yeni refresh token gəlir: köhnəsini silin. Köhnə refresh token ikinci dəfə gəlsə, Clomni bunu oğurluq sayır və bütün token ailəsini ləğv edir, administrator app-ı yenidən qoşmalı olur. Bir quraşdırmanı eyni anda iki prosesdən yeniləməyin. scope göndərsəniz, token daralır, genişlənmir.

6. 6

   İşləyən scope-lar və ləğv

   Hər sorğuda işləyən scope-lar: administratorun razılıq verdiyi scope-lar ilə app-ın hazırda təsdiqlənmiş scope-larının kəsişməsi. Yeni scope təsdiqlənəndə mövcud quraşdırmalara özü əlavə olunmur: administrator app-ı yenidən qoşmalıdır. Administrator app-ı Parametrlər › İş sahəsi parametrləri › App-lar › «Bağlı app-lar» bölməsində ləğv edəndə bütün tokenlər dərhal dayanır və app-ın webhook-una app.uninstalled gedir. Qoşan şəxs artıq administrator deyilsə, tokenlər 403 installation_owner_not_admin qaytarır. Tokeni özünüz POST /v1/oauth/revoke ilə ləğv edə bilərsiniz.

7. 7

   Review-dan əvvəl sınaq və kataloq

   Review-dan əvvəl app-ı onun öz workspace-ində, sahibi kimi qoşub test kanalında sınaya bilərsiniz: təsdiqlənməmiş scope-lar yalnız orada işləyir («Test kanalı» məqaləsi). Listinq təsdiqlənəndən sonra app paneldəki kataloqda görünür, «Qoş» düyməsi app-ın quraşdırma ünvanını (install_url) açır və axını app-ınız başladır.

8. 8

   Token səhvləri

   • 400 invalid_grant: kod və ya refresh token səhvdir, vaxtı bitib, artıq işlədilib, redirect_uri və ya code_verifier uyğun deyil, quraşdırma ləğv olunub.
   • 401 invalid_client: client_id və ya client_secret səhvdir, ya da secret-i olan app onu göndərməyib.
   • 400 unauthorized_client: app public deyil, dayandırılıb və ya arxivlənib.
   • 400 invalid_scope, unsupported_grant_type.