Developer API-də tokenlər və autentifikasiya

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

Addımlar

1. 1

   Ünvan və başlıqlar

   • Base URL (bütün ünvanların başlanğıcı): https://api.clomni.ai/v1, yalnız HTTPS.
   • Token başlığı: Authorization: Bearer <token>.
   • Gövdə göndərəndə: Content-Type: application/json, UTF-8. Cavab JSON-dur.
   • Xəta mətni default azərbaycancadır, Accept-Language: en ilə ingiliscə gəlir.

   Ünvanda workspace nömrəsi yazılmır: GET /v1/conversations tokenin workspace-indəki söhbətləri qaytarır. API ilə edilən əməliyyat tokenin sahibinin adından görünür: daxili app-da app sahibi, public app-da app-ı qoşan administrator.

2. 2

   Token növləri

   • Şəxsi token (clomni_pat_): portalda yaradılır, 30, 60, 90, 180 və ya 365 gün (default 90). Skript, test, kiçik daxili iş üçün.
   • App tokeni (clomni_at_): server client_id və client_secret ilə özü alır, 1 saat işləyir. Daimi server inteqrasiyası üçün.
   • OAuth access token (clomni_at_, 1 saat) və refresh token (clomni_rt_, 90 gün): public app-ın hər quraşdırması üçün. Bax: «Public app və OAuth» məqaləsi.
   • Client secret (clomni_secret_) və webhook secret (whsec_): portalda yaradılır, yalnız bir dəfə göstərilir.

   Clomni tokenləri yalnız həş şəklində saxlayır, ona görə tokeni ikinci dəfə göstərə bilmir. İtirsəniz, yenisini yaradın və köhnəsini ləğv edin.

3. 3

   Şəxsi token yaradın

   Portalda app-ı açın, «Etimadnamələr» bölməsində «Token yarat» basın. Ad (60 simvola qədər), scope-lar və müddəti seçin. Scope-lar yalnız təsdiqlənmişlərdəndir. messages:send və conversations:write review-dan əvvəl də seçilə bilər, amma təsdiqə qədər yalnız test kanalında işləyir. Bir app-da eyni anda ən çox 10 aktiv şəxsi token olur. Public app-da şəxsi token yoxdur.

4. 4

   App tokeni alın (client credentials)

   «Etimadnamələr» bölməsində client_id görünür (capp_ ilə başlayır). «Secret yarat» ilə clomni_secret_... alın. Secret-i yenidən yaradanda köhnəsi daha 7 gün işləyir. Token sorğusu:

   curl -X POST https://api.clomni.ai/v1/oauth/token \
     -u "$CLOMNI_CLIENT_ID:$CLOMNI_CLIENT_SECRET" \
     -d grant_type=client_credentials \
     -d scope="conversations:read messages:read"

   Cavabda access_token (clomni_at_...), expires_in: 3600, scope və workspace_id olur. scope yazılmasa, bütün təsdiqlənmiş scope-lar verilir. Tokeni bitənə qədər yaddaşda saxlayıb təkrar işlədin: /oauth/token dəqiqədə 20 sorğu ilə məhdudlaşır. Refresh token yoxdur, vaxt bitəndə eyni sorğunu göndərin. Səhvlər: invalid_client (401, client məlumatı səhvdir), unauthorized_client (app dayandırılıb, arxivlənib, sahibi administrator deyil və ya təsdiqlənmiş scope yoxdur), invalid_scope, unsupported_grant_type.

5. 5

   Tokeni yoxlayın: GET /me

   GET /v1/me tokenin kimə aid olduğunu və hansı scope-ların işlədiyini qaytarır, scope tələb etmir:

   curl https://api.clomni.ai/v1/me \
     -H "Authorization: Bearer clomni_pat_xxx"

   Cavabda app, workspace, user, token (kind, expires_at, scopes) və scopes olur. token.scopes tokenə yazılanlardır, scopes isə indi işləyənlərdir: app-dan silinən və ya təsdiqlənməyən scope orada olmur.

6. 6

   Token nə vaxt özü dayanır

   • Müddəti bitəndə: 401 token_expired və ya invalid_token.
   • App sahibi parolunu dəyişəndə.
   • Clomni app-ı dayandıranda (403 app_suspended) və ya app arxivlənəndə.
   • App sahibi workspace-də administrator olmayanda: 403 app_owner_not_admin. Rol qaytarılanda yenidən işləyir.
   • Workspace dayandırılanda: 403 account_suspended, yalnız workspace:read işləyir.

   Şəxsi tokeni portalda ləğv edin, ləğv dərhal qüvvəyə minir. App tokenini POST /v1/oauth/revoke ilə ləğv edin.

7. 7

   Tokeni qoruyun

   Token və secret yalnız serverdə saxlanır: brauzer kodunda, mobil tətbiqdə, açıq repoda və loglarda olmamalıdır. Hər mühit üçün ayrıca token yaradın, loga tokenin yalnız son 4 simvolunu yazın. Sızdığını düşünürsünüzsə, tokeni dərhal ləğv edin və ya secret-i dəyişin, sonra [email protected]ə yazın.