Kimlik doğrulama

FreeMaint iki kimlik doğrulama mekanizmasını kabul eder: JWT'ler (/auth/login tarafından verilir, web ve mobil uygulamalarımız tarafından kullanılır) ve API anahtarları (/company-settings/api'de oluşturulur, kendi entegrasyonlarınız tarafından kullanılır).

JWT (kullanıcı oturumları)

1. POST /auth/login — Gövde: {email, password}. {access_token, refresh_token} döndürür.
2. Authorization başlığını gönder — Her istekte: Authorization: Bearer <access_token>.
3. Süresi dolduğunda yenile — Yeni bir access_token almak için refresh_token ile POST /auth/refresh isteği gönderin. Erişim belirteçlerinin geçerliliği 2 saattir.

API anahtarı (sunucu entegrasyonları)

1. /company-settings/api veya /profile/api-keys adresini açın — Yöneticiler, Business planından itibaren anahtarları Şirket Ayarları > API altında oluşturur. Rolünde “Kişisel API anahtarları oluşturma” izni bulunan bir kişi, kendi anahtarlarını Profil > Güvenlik > API anahtarları altında oluşturur. "Entegrasyonları yönetme" yetkisine sahip bir rol (örneğin Entegrasyon yöneticisi şablonu) yönetici olmadan şirket anahtarlarını oluşturabilir, iptal edebilir ve silebilir; bir anahtarı başka birine yalnızca yönetici devredebilir.
2. 'Yeni anahtar'ı tıklayın — İsteğe bağlı olarak bir son kullanma tarihi ve bir erişim düzeyi ayarlayın (varsayılan olarak Salt okunur). Ham anahtar yalnızca BİR KEZ gösterilir — hemen kopyalayın.
3. Anahtarı kullan — Her istekte Authorization: Bearer fmk_<rawKey> başlığını gönderin. Format: fmk_ ile başlar ve ardından 32 onaltılık karakter gelir.

Güvenlik notları

• API anahtarları SHA-256 karmaları olarak depolanır; açıklama iletişim kutusunu kapattığınızda ham değer kurtarılamaz
• Bir anahtarın iptal edilmesi onu anında devre dışı bırakır; satır denetim için tutulur
• Her anahtar tek bir şirkete aittir ve yalnızca o şirketin verilerine erişir — başka bir şirketin kaydı basitçe bulunamaz
• Kısa ömürlü entegrasyonlar için anahtarlara isteğe bağlı bir expiresAt değeri verilebilir
• Erişim düzeyleri, sahibin izinlerinin üzerine konan bir tavandır: READ (varsayılan — yalnızca sorgular), READ_STOCK (sorgular + adjustStock — yalnızca tüketim yapan kiosklar için ideal), FULL (sahibin rolünün izin verdiği her işlem)
• Her anahtar sahibi olarak davranır: her çağrı sahibin izinlerini ve veri görünürlüğünü taşır, anahtarın yazdığı her şey de sahibin adıyla imzalanır. Sahip devre dışı bırakılırsa, bir yönetici anahtarı Şirket Ayarları > API altında başka bir kişiye devredene kadar anahtar reddedilir (401, kod API_KEY_OWNER_INACTIVE) — anahtarın değeri değişmez.

Bir entegrasyonu test etme

Ayrı bir kum havuzu ortamı yoktur: bir API anahtarı her zaman ait olduğu şirketin gerçek verilerine erişir. Güvenle test etmenin iki yolu var. (1) İkinci bir şirketi test şirketiniz olarak kullanın — şirketler arasındaki yalıtım, tüm müşterileri birbirinden ayıran mekanizmanın aynısıdır, dolayısıyla orada yaptığınız hiçbir şey üretim verilerinize ulaşamaz. API anahtarları Business planı gerektirir, bu yüzden o şirketin de Business planında olması gerekir: ücretsiz bir şirket anahtar oluşturamaz. (2) Yalnızca okuma işleri için READ erişim düzeyinde bir anahtar oluşturun: her sorguyu çalıştırır, hiçbir mutasyonu çalıştıramaz, yani hiçbir şeyi değiştiremez. Yazmaya hazır olduğunuzda READ_STOCK anahtarı yalnızca adjustStock'a izin verir.