Bu sayfa, bir programdan kuruluşun kullanıcılarını yönetmek isteyen yöneticilere yöneliktir. Bir API anahtarının üyelerle ne yapamayacağını, bir kimlik sağlayıcının üyeleri SCIM 2.0 üzerinden nasıl oluşturup kaldırdığını ve hangi webhook olaylarının üye değişikliklerini bildirdiğini açıklar.
Bir API anahtarının yapamadıkları
Üyeler, davetler, roller ve gruplar yalnızca uygulamada yönetilir. Hangi izinleri vermeye çalışırsanız çalışın, hiçbir API anahtarı bu rotaları çağıramaz:
| Görev | Nerede yapılır |
|---|---|
| Üyeleri listeleme, bir üyeyi okuma, etkinliklerini görme | Üyeler sayfası |
| Kişileri davet etme, davetleri yeniden gönderme, hatırlatma veya iptal etme | Üyeler sayfası (Üye Davet Et) |
| Bir üyenin rolünü veya gruplarını değiştirme, askıya alma, kaldırma | Üyenin sayfası |
| Rolleri, grupları ve izin matrisini düzenleme | Ayarlar > Erişim Denetimi |
| Sahipliği devretme | Uygulamada (yalnızca Sahip) |
| Üyeleri kimlik sağlayıcınızdan oluşturun, güncelleyin ve devre dışı bırakın | SCIM 2.0 (aşağıda) |
Bu bilinçli bir tasarımdır. Bir anahtar, Hermetry’nin kimlik ve erişim bölümlerine ait izinlere asla sahip olamaz: üyeler, davetler, kuruluş ayarları, API anahtarları, oturumlar ve oturum açma. Sızan bir anahtar bir kişi ekleyemez, bir rolü yükseltemez veya dış bir adrese davet gönderemez. Bir üye veya davet rotasını çağıran anahtar şu yanıtı alır:
{ "message": "API key does not have the required permission.", "code": "FORBIDDEN" }
durum kodu 403 ile. Davetin kabul edilmesi veya reddedilmesi, davet edilen kişi oturum açmışken yapılır; anahtarlar hesap rotalarında hiçbir zaman çalışmaz. Tam kural için bkz. Kimlik doğrulama.
Üyeleri SCIM 2.0 ile sağlama
SCIM, kimlik sağlayıcınızın üyeleri oluşturmasına, güncellemesine ve devre dışı bırakmasına olanak tanır. Uygulamadaki kurulum (uç nokta ve SCIM belirteci) Tek oturum açma (SAML) ve sağlama sayfasındadır. Bu bölüm, SCIM’i kendisi çağıran bir entegrasyon için rota başvurusudur.
Tüm SCIM yolları https://<your host>/tenant/<tenantId>/api/scim/v2 altındadır. SCIM belirtecini Authorization: Bearer <token> içinde gönderin. Okumalar scim:read kapsamını, yazmalar scim:write kapsamını gerektirir. Belirteç, yoldaki kuruluşa ait olmalıdır.
| Yöntem | Yol | Kapsam | İşlev |
|---|---|---|---|
| GET | /Users | scim:read | Üyeleri listele |
| POST | /Users | scim:write | Bir üye oluştur; Location ve ETag ile 201 |
| GET | /Users/{id} | scim:read | Bir üye, ETag ile birlikte |
| PUT | /Users/{id} | scim:write | Bir üyeyi değiştir |
| PATCH | /Users/{id} | scim:write | Bazı öznitelikleri değiştir |
| DELETE | /Users/{id} | scim:write | Sağlamayı kaldır; 204 |
| GET, POST | /Groups | okuma / yazma | Grupları listele veya oluştur |
| GET, PUT, PATCH, DELETE | /Groups/{id} | okuma / yazma | Bir grup |
| GET | /ServiceProviderConfig, /ResourceTypes, /Schemas | yok | Kimlik sağlayıcılar için keşif |
Yanıtlar ve hatalar Content-Type: application/scim+json kullanır.
Öznitelikler nasıl eşlenir
| SCIM özniteliği | Hermetry’de |
|---|---|
id | Bu kuruluştaki üye kimliği |
userName, birincil emails değeri | Hesap e-postası |
externalId | Üye sayfasındaki SCIM harici kimliği (en fazla 256 karakter) |
active | Üye durumu: true Etkin, false Etkin değil |
name, displayName | Adları güncel tut açıkken (varsayılan) ve hesap yalnızca kuruluşunuza aitken saklanır |
Yeni bir üye SCIM varsayılan rolünü alır (SCIM ayarlarında değiştirmediyseniz Kullanıcı). Gruplardan gelen roller Gruplar ve roller bölümünde ayarlanır.
Listeler
GET /Users, startIndex (1’den başlar), count (varsayılan 100, en fazla 200), sortBy ve sortOrder (ascending veya descending) okur. Tek geçerli filtreler userName veya externalId üzerinde eşitlik kontrolüdür:
GET /Users?filter=userName eq "ana@example.com"
GET /Users?filter=externalId eq "00u1a2b3c4"
Diğer tüm filtreler scimType invalidFilter ile 400 yanıtı verir.
Oluşturma kuralları
- Yeni bir e-posta adresi hesabı ve üyeyi oluşturur.
- Zaten var olan ancak kuruluşunuzun üyesi olmayan bir hesap,
409(uniqueness) ile reddedilir: “Bu userName ile bir hesap zaten var ve bu kuruluşun üyesi değil. Davet yoluyla katılır.” Önce kişiyi uygulamada davet edin; bundan sonra membership SCIM tarafından yönetilir.
Başkaları tarafından yapılan değişiklikler
GET /Users/{id} bir ETag döndürür. Bunu PUT, PATCH veya DELETE isteklerinde If-Match içinde gönderin; üye bu arada değiştiyse yanıt 412 olur. Bir GET üzerindeki If-None-Match, hiçbir şey değişmediyse 304 yanıtı verir.
Gruplar
Grup rotaları, Gruplar SCIM ayarlarında açılana kadar 501 yanıtı verir (“SCIM Grupları bu kiracı için etkin değil.”). Gruplar açıkken bir üyenin rolü, rollere eşlenmiş gruplarını izler. Son etkin Sahip, bir grup değişikliğiyle asla düşürülmez.
Örnek
curl 'https://<your-host>/tenant/{tenantId}/api/scim/v2/Users?filter=userName%20eq%20%22ana@example.com%22' \
-H 'Authorization: Bearer sk_live_…'
{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
"totalResults": 1,
"startIndex": 1,
"itemsPerPage": 1,
"Resources": [ { "id": "4b2e…", "userName": "ana@example.com", "active": true, "…": "…" } ]
}
SCIM hataları
| Durum | scimType | Ne zaman |
|---|---|---|
| 400 | invalidFilter | userName eq veya externalId eq dışındaki bir filtre |
| 400 | invalidSyntax, invalidValue | JSON olmayan veya şemayı bozan bir gövde |
| 401 | yok | “Invalid bearer token.”: belirteç bilinmiyor, süresi dolmuş, başka bir kuruluşa ait veya kapsamı eksik |
| 404 | yok | Kuruluşunuzda bu kimliğe sahip üye yok |
| 409 | uniqueness | E-posta alınmış, ya da hesap var ama üye değil |
| 412 | yok | If-Match, üyenin mevcut ETag değeriyle eşleşmiyor |
| 429 | yok | “Too many requests. Please slow down.” |
| 501 | yok | Gruplar açık değil |
Üye değişikliklerini webhook’larla izleyin
Diğer bir sistemi, sorgulama yapmadan güncel tutmak için bir webhook’u bu olaylara abone edin (bkz. Webhooks):
| Olay | Gönderildiği zaman |
|---|---|
member.created, member.updated, member.deleted | Bir üye eklendiğinde, değiştiğinde veya kaldırıldığında |
invitation.sent, invitation.accepted, invitation.declined, invitation.revoked | Bir davetin durumu değiştiğinde |
scim.user.provisioned, scim.user.updated, scim.user.deprovisioned | Kimlik sağlayıcınız bir üyeyi SCIM üzerinden değiştirdiğinde |

