Kimlik doğrulama

Programlar API anahtarları ile kimlik doğrular. Bir anahtar, onu oluşturan üye adına hareket eder ve anahtara verdiğiniz izinlerle sınırlıdır. Token değişimi yoktur: anahtarın kendisi kimlik bilgisidir ve her çağrıda gönderilir.

API anahtarları yöneticiler tarafından API Keys üzerinden yönetilir (menünün Developer bölümünde). Anahtar oluşturmak için API anahtarları içeren bir plan gerekir.

Bir anahtar oluşturun

1. API Keys bölümünü açın ve New API Key seçeneğini seçin.
2. Bir Name girin (en fazla 100 karakter) ve isteğe bağlı olarak bir Description (en fazla 500 karakter) girin.
3. Module permissions altında, anahtarın neler yapabileceğini bir modül seçerek belirleyin. Her modül bir Read only ön ayarı sunar; ayrıca tek tek izinleri de işaretleyebilirsiniz. Bir modül veya izin bulmak için Search modules or permissions… alanını kullanın. Seçici yalnızca sizin kendinizin sahip olduğu izinleri listeler: “Anahtar, en fazla sizin yapabildiklerinizi yapabilir. Kendi haklarınız daha sonra daralırsa, anahtar da bunları kaybeder.”
4. Expires on alanını ayarlayın. Varsayılan, bugünden itibaren 90 gündür; en fazla bir yıl olabilir (“Varsayılan 90 gündür, en fazla bir yıl.”).
5. İsteğe bağlı olarak IP allowlist alanını doldurun: her satıra bir alt ağ yazın, örneğin 10.0.0.0/8 veya 203.0.113.7/32. Boş bırakmak, kuruluşunuzun izin verdiği her adres anlamına gelir.
6. Bir entegrasyonun kendi belgeleri istemedikçe Integration scopes (advanced) alanını boş bırakın (örneğin SCIM provisioning).
7. Create Key seçeneğini seçin ve anahtarı hemen kopyalayın.

İki adımlı doğrulama veya bir passkey kullanıyorsanız, Hermetry anahtar oluşturulmadan önce bunu onaylamanızı ister. Bir üyenin yerine geçerken anahtar oluşturulamaz.

Anahtar biçimi

sk_live_<first 8 characters of the organisation id>_<48 random hexadecimal characters>

live anahtarları üretim hizmetine, test anahtarları test kurulumlarına aittir; böylece ikisi birbirine karıştırılamaz.

Bir anahtarı kullanın

Anahtarı her çağrıda Authorization başlığında gönderin:

curl "https://<your host>/tenant/<tenantId>/api/iot/devices" \
  -H "Authorization: Bearer sk_live_…"

• API anahtarı içeren bir istek yalnızca o anahtar olarak değerlendirilir. Aynı istekteki bir tarayıcı çerezi yok sayılır.
• Anahtarlar yalnızca kuruluşunuzun yollarında çalışır (/tenant/<tenantId>/api/...). Anahtarın kuruluşu, yoldaki tenantId ile eşleşmelidir.
• Bir anahtar hiçbir zaman platform, hesap veya oturum açma yollarında çalışmaz.

Bir anahtarın yapabilecekleri

Her çağrıda, bunların hepsinin geçerli olması gerekir:

1. Anahtar, yolun gerektirdiği izne sahiptir.
2. İznin modülü kuruluşunuz için açıktır.
3. Anahtarı oluşturan üye izne şu anda sahiptir: rolleri, grupları ve erişim politikalarınız dikkate alınır.
4. Üye hâlâ aktif bir üyedir ve kuruluş aktiftir.

Bir anahtar, bir Owner tarafından oluşturulmuş olsa bile en fazla Admin rolüyle hareket eder. Bu nedenle bir anahtar hiçbir zaman yalnızca Owner’a özgü izinlere sahip olamaz (örneğin ham cihaz komutları, firmware imzalama anahtarları, tehlikeli cihaz ayarları, bir webhook gizli anahtarını yenileme) ve kimlik ve erişim modüllerinin izinlerine (oturum açma, hesaplar, API anahtarları, üyeler, oturumlar) asla sahip olamaz. Dolayısıyla bir anahtar, anahtar oluşturamaz veya döndüremez.

Servis anahtarları

Bir anahtar normalde oluşturanı kuruluştan ayrıldığında çalışmayı bırakır. Bir Owner anahtarı açıp Mark as service key seçeneğini seçebilir: bu durumda anahtar, oluşturanı ayrıldıktan sonra da çalışmaya devam eder (“Evet: oluşturanından sonra da yaşar”) ve onu işaretleyen Owner gibi hareket eder.

İzin verilen ağlar

Bir anahtarın IP allowlist listesi CIDR biçiminde en fazla 100 alt ağ içerebilir; tek bir adres /32 ile yazılır. Bunun dışındaki yerlerden gelen çağrılar 403 ile reddedilir: “Bu API anahtarı geçerli IP adresinden kullanılamaz.” Kendi listesi olmayan bir anahtar, kuruluşun varsayılan listesini kullanır (aşağıdaki Settings bölümüne bakın). Kuruluşunuzun oturum açma için kendi IP izin ve engel listeleri anahtarlar için de geçerlidir.

Son kullanma

Her anahtarın bir son kullanma tarihi vardır. Varsayılan 90 gündür; en geç tarih 365 gün sonrasıdır, ancak kuruluşunuz daha düşük bir üst sınır belirlemişse bu daha kısa olabilir. Süresi dolan anahtarlar kendiliğinden durur. Bir yönetici, süresi dolan anahtarları ayrıca temizleyebilir (POST /api/api-keys/sweep-expired); bu, onları pasif olarak işaretler ve anahtar başına bir api_key.expired webhook olayı gönderir.

Döndürme, devre dışı bırakma ve iptal

Bir anahtarın Identity, Usage (son kullanım, son kullanım IP’si, toplam doğrulama), Module permissions ve Rotation history bilgilerini görmek için anahtarı açın.

• Rotate key aynı izinler, kapsamlar, ağ listesi ve ortamla bir halef anahtar oluşturur. Grace window (days) değerini belirleyin: eski anahtar bu süre dolana kadar çalışmaya devam eder. “0, eski anahtarı hemen iptal eder.” Yeni gizli anahtarı hemen kopyalayın.
• Deactivate bir anahtarı, tekrar Activate edene kadar durdurur. Döndürülmüş bir anahtar yeniden etkinleştirilemez: “Döndürülmüş bir anahtar yeniden etkinleştirilemez; halefini kullanın.”
• Revoke anahtarı siler: “Bu anahtarı kullanan tüm entegrasyonlar hemen çalışmayı durduracak. Bu işlem geri alınamaz.”
• Edit anahtarın modül izinlerini değiştirir. Herhangi bir izni kaldırabilirsiniz, ancak yalnızca sahip olduğunuz izinleri ekleyebilirsiniz. Entegrasyon kapsamları yalnızca daraltılabilir.

Bir olay anında, bir yönetici kuruluşun etkin tüm anahtarlarını tek adımda iptal edebilir.

{
    "graceSeconds": 86400
}

curl -X POST 'https://<your-host>/tenant/{tenantId}/api/api-keys/{apiKeyId}/rotate' \
  -H 'Content-Type: application/json' \
  -d '{"graceSeconds":86400}'

{
    "key": {
        "name": "Plant ERP",
        "…": "…"
    },
    "rawKey": "sk_live_…"
}

{
    "message": "Only an active, unexpired key that has not been rotated yet can be rotated.",
    "code": "CONFLICT"
}

Anahtarları HTTP üzerinden yönetin

Anahtarları oturum açmış bir yönetici yönetir. Bir API anahtarı anahtar oluşturamaz, değiştiremez veya döndüremez.

{
    "name": "Plant ERP",
    "permissions": [
        "iot_device.devices.read",
        "telemetry.read"
    ],
    "ipAllowlist": [
        "203.0.113.0/24"
    ]
}

curl -X POST 'https://<your-host>/tenant/{tenantId}/api/api-keys' \
  -H 'Content-Type: application/json' \
  -d '{"name":"Plant ERP","permissions":["iot_device.devices.read","telemetry.read"],"ipAllowlist":["203.0.113.0/24"]}'

{
    "key": {
        "name": "Plant ERP",
        "…": "…"
    },
    "rawKey": "sk_live_…"
}

{
    "message": "Select at least one module permission or integration scope."
}

{
    "message": "An API key can only receive permissions you hold yourself."
}

{
    "message": "The expiry date must be in the future."
}

Bir anahtarı kontrol edin

{
    "scope": "read"
}

curl -X POST 'https://<your-host>/tenant/{tenantId}/api/api-keys/verify' \
  -H 'Content-Type: application/json' \
  -d '{"scope":"read"}'

{
    "valid": true,
    "key": {
        "name": "Plant ERP",
        "…": "…"
    }
}

{
    "valid": false,
    "message": "scope must be a string"
}

{
    "valid": false,
    "message": "Invalid or expired API key."
}

{
    "valid": false,
    "message": "Too many requests."
}

Ayarlar

Yöneticiler kuruluşun anahtar politikasını API Keys > ayarlar (dişli düğmesi) üzerinden belirler:

Anahtarlar için geçerli diğer sınırlar Errors and rate limits sayfasındadır.

Anahtarları izleme

• Her anahtar, son kez ne zaman ve hangi adresten kullanıldığını kaydeder.
• 14 gün kullanılmayan ve ardından yeni bir adresten kullanılan bir anahtar bir denetim olayı oluşturur (“Uykudaki bir API anahtarı yeni bir adresten kullanıldı”); anahtar ve adres başına saatte en fazla bir kez.
• Reddedilen her anahtar çağrısı denetim günlüğüne yazılır.
• Webhook’lar size anahtarlarla ilgili bilgi verebilir: api_key.created, api_key.updated, api_key.rotated, api_key.deleted, api_key.expired.

Kontrol listesi için API key hardening sayfasına bakın.