İçeriğe geç

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 anahtar 400 cookie_with_key alı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

KapsamAçıklama
employees:readÇalışanları okuma
employees:writeÇalışan oluşturma ve güncelleme
org:readOrganizasyon yapısını okuma
leave:readİzinleri okuma
shifts:readVardiyaları okuma
events:readOlay akışını okuma
health_scheduling:readNöbet çizelgelerini okuma
health_premiums:writeNöbet ücreti ve prim verisi yazma
field:salaryMaaş
field:national_idT.C. kimlik no
field:ibanIBAN
field:piiKişisel bilgiler
field:healthSağ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/employees için anahtarda employees:write ve employees:read birlikte bulunmalıdır.
  • Kapsamı olmayan işleme 403 insufficient_scope, rolün izin vermediği işleme 403 forbidden döner.
  • events:read yalnı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.