Autentifikasiya

Hər sorğu API açarı ilə autentifikasiya olunur. Onu Bearer token kimi göndərin:

Authorization: Bearer gsk_live_xxx

Əgər Bearer token sizin stekdə əlverişsizdirsə, x-api-key: gsk_live_xxx başlığı da qəbul edilir. Açarsız hər sorğu title: invalid_key ilə 401 alır.

Açarın formatı

gsk_live_<id>_<secret> və ya gsk_test_<id>_<secret>. gsk_live açarı real iş görür və ödənişlidir. gsk_test açarı sandbox mühitində işləyir: alətlər simulyasiya olunur və heç nə üçün ödəniş tutulmur; onunla obyektləri, lidləri və digər real məlumatları dəyişmək olmaz. Açarın növünü onu yaradarkən seçin.

Gizli açar yaradılarkən bir dəfə göstərilir. GREM yalnız onun heşini saxlayır, ona görə itirilmiş açarı bərpa etmək mümkün deyil - yenisini yaradın və köhnəsini ləğv edin.

Açarların idarə edilməsi

Kabinetdə, API → Açarlar bölməsində:

• Yarat - etiketli açar yaradın. Əlavə ayarlarda icazələri və etibarlılıq müddətini günlərlə seçmək olar. Seçim edilmədikdə açar bütün icazələri alır.
• Döndər (rotasiya) - yeni gizli açar buraxın; köhnəsi 24 saat işləməyə davam edir ki, onu inteqrasiyanızda əvəz edə biləsiniz.
• Geri çək - açar dərhal və həmişəlik işləməyi dayandırır.

Açarın statusu siyahıda göstərilir: active - işləyir; suspended - API girişi administrator tərəfindən dayandırılıb (geri qaytarıla bilər, açar məhv edilmir); revoked - ləğv edilib. Etibarlılıq müddəti olan açar bu müddət bitdikdən sonra artıq qəbul edilmir (401).

Agentlik açarları

Agentliyin sahibi və ya meneceri agentlik adından açar buraxa bilər: bunun üçün açarlar siyahısını agentlik rejiminə keçirin. Belə açar:

• şəxsi deyil, agentliyin obyektlərini və lidlərini görür;
• agentliyin ümumi siyahısından lidləri götürə və onları geri qaytara bilər (Lidlər);
• obyektləri agentliyə köçürə və agent təyin edə bilər (Obyektlər).

Açarı bir agentə bağlamaq olar - bu halda o, həmin agent kimi, onun icazələri ilə işləyir.

İcazələr

Hər açarın icazələr (scope) dəsti var. Lazımi icazə olmadan edilən çağırış title: forbidden_scope ilə 403 qaytarır. Əməliyyatın tələb etdiyi icazə onun /openapi.json faylındakı təsvirində göstərilir (x-required-scope sahəsi).

Heç bir icazə olmadan GET /ping, GET /me, GET /dictionaries, GET /objects, GET /voices, GET /tools/status və GET /works çağırmaq olar.

Bu hansı açardır

curl https://developers.grem.capital/api/v1/me \
  -H "Authorization: Bearer gsk_live_xxx"

GET /me açarın identifikatorunu və prefiksini, kimə məxsus olduğunu (subjectType: user və ya agency, subjectId, agent açarı üçün isə agencyMemberId), verilmiş icazələri, məhz bu açara tətbiq olunan sorğu limitlərini (rateLimit.rpm dəqiqədə və rateLimit.rpd gündə) və etibarlılıq müddətini qaytarır. Gizli açar heç vaxt qaytarılmır. Pulsuzdur.

Təhlükəsizlik

• Açarları server tərəfindəki mühit dəyişənlərində və ya sirr menecerində saxlayın.
• Hər inteqrasiya üçün yalnız lazımi icazələri olan ayrıca açar istifadə edin - birini ləğv etmək digərlərinə təsir etmir.
• Açarları müntəzəm olaraq rotasiya edin.
• Sorğular yalnız HTTPS vasitəsilə qəbul edilir.

Əlaqəli

• Xətalar - 401 və 403 ətraflı.
• Limitlər və ödəniş - rpm və rpd nə deməkdir.