Kimlik ve kapsamlar
API anahtarı, rol ve bağlama, kapsamlar ve sınıflı alanlar.
Geliştirici belgesi
API anahtarı
Anahtarları hesap sahibi Ayarlar › API ekranından oluşturur, döndürür ve iptal eder. Bir anahtarın adı, rolü, bağlaması, kapsamları, geçerlilik süresi ve isteğe bağlı izinli IP adresleri vardır.
- Tam anahtar
biik_sk_önekiyle başlar ve yalnız oluşturulurken bir kez gösterilir. biik anahtarın kendisini saklamaz, yalnız doğrulamak için özetini tutar: kaybolan anahtar geri getirilemez, yenisi oluşturulur. - Geçerlilik süresi varsayılan 90 gün, en çok 365 gündür. Süresi biten anahtar çalışmaz.
- İzinli IP adresleri listesine en çok 20 adres ya da aralık yazılır. Liste boşsa anahtar her adresten çalışır.
- Döndürme yeni bir anahtar verir. Eski anahtar seçtiğiniz örtüşme süresi boyunca çalışmaya devam eder (varsayılan 24 saat, en çok 168 saat); anahtarın sızdığından şüpheleniyorsanız döndürmeyi "Hemen" seçin ya da anahtarı iptal edin.
- Oluşturma ve döndürme ek doğrulama ister. İptal istemez ve her zaman açıktır.
- Ekrandaki İstek günlüğü her çağrıyı (yöntem, yol, durum, anahtar) gösterir. API'nin yaptığı her yazım ürünün denetim kaydına, yapanı anahtar olarak yazılır.
İsteği doğrulama
Anahtar yalnız Authorization başlığıyla gönderilir:
Authorization: Bearer biik_sk_...
- Sorgu dizesindeki anahtar
400 key_in_query, çerezle birlikte gönderilen anahtar400 cookie_with_keyalır. - Geçersiz, süresi dolmuş ve iptal edilmiş anahtar aynı yanıtı alır:
401 unauthorized. Hangisinin olduğu söylenmez. - API tarayıcıdan çağrılmak için değildir: CORS başlığı dönmez. Anahtarı sunucu tarafında tutun.
Rol ve bağlama
Anahtar oluşturulurken bir rol seçilir. Rolün izinleri ve kapsamı (tüm hesap, bir şirket, bir şube ya da bir birim) anahtarın görebileceği en geniş kümedir. Kapsamlar bu kümeyi yalnız daraltır, genişletmez.
- Anahtarın göremediği kayıt, başka bir hesabın kaydı ve var olmayan kayıt aynı yanıtı alır:
404 not_found. Listeler görünmeyen satırı hiç döndürmez, sayfa boyutu ve imleç yalnız görünen satırları sayar. - Anahtarı oluşturan kişi hesaptan ayrılsa da anahtar çalışır; hesap sahiplerine bildirim gider ve anahtar listede "Gözden geçirin" diye işaretlenir.
Kapsamlar
| Kapsam | Açıklama |
|---|---|
employees:read | Çalışanları okuma |
employees:write | Çalışan oluşturma ve güncelleme |
org:read | Organizasyon yapısını okuma |
leave:read | İzinleri okuma |
shifts:read | Vardiyaları okuma |
events:read | Olay akışını okuma |
health_ | Nöbet çizelgelerini okuma |
health_ | Nöbet ücreti ve prim verisi yazma |
field:salary | Maaş |
field:national_ | T.C. kimlik no |
field:iban | IBAN |
field:pii | Kişisel bilgiler |
field:health | Sağlık bilgileri |
- Kaynak kapsamı o kaynağın uçlarını açar:
employees:readçalışan okumayı,employees:writeçalışan oluşturmayı ve güncellemeyi. Yazan uç yanıtında kaynağın güncel hâlini döndüğü için okuma kapsamını da ister:POST /api/v1/employeesiçin anahtardaemployees:writeveemployees:readbirlikte bulunmalıdır. - Kapsamı olmayan işleme
403 insufficient_scope, rolün izin vermediği işleme403 forbiddendöner. events:readyalnız hesabın tamamını gören bir role verilir; olaylar kayıt düzeyinde süzülmez.
Sınıflı alanlar
T.C. kimlik numarası (national_id), IBAN (iban), ücret (salary), kişisel bilgiler (personal) ve takvimde gizli izin türü (health) sınıflı alanlardır.
- Sınıflı bir alan yalnız anahtar ilgili
field:<sınıf>kapsamını ve rol aynı alan sınıfını birlikte taşıyorsa döner. - Koşul tutmazsa alanın adı da yanıtta yoktur. Koşul tutar ama değer yoksa alan
null'dır. - Listeler hiçbir sınıflı alan taşımaz; sınıflı alanlar yalnız tek kayıt okumasında döner. Değer dönen her okuma ürünün erişim kaydına yazılır; okuyan anahtardır.
- Sınıflı alanlar bu sürümde API'den yazılamaz.