Yeni: Yapay zekâ güvenlik duvarı tüm platformu izliyor ve her olayı sade bir dille açıklıyor. Nasıl çalıştığını görün

Üyeler API’si

Bir programın bir kuruluşun üyeleriyle yapabilecekleri: SCIM 2.0 ile sağlamak ve webhook'larla değişiklikleri izlemek. API anahtarları üyeleri veya davetleri yönetemez.

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örevNerede 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üzenlemeAyarlar > Erişim Denetimi
Sahipliği devretmeUygulamada (yalnızca Sahip)
Üyeleri kimlik sağlayıcınızdan oluşturun, güncelleyin ve devre dışı bırakınSCIM 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öntemYolKapsamİşlev
GET/Usersscim:readÜyeleri listele
POST/Usersscim:writeBir üye oluştur; Location ve ETag ile 201
GET/Users/{id}scim:readBir üye, ETag ile birlikte
PUT/Users/{id}scim:writeBir üyeyi değiştir
PATCH/Users/{id}scim:writeBazı öznitelikleri değiştir
DELETE/Users/{id}scim:writeSağlamayı kaldır; 204
GET, POST/Groupsokuma / yazmaGrupları listele veya oluştur
GET, PUT, PATCH, DELETE/Groups/{id}okuma / yazmaBir grup
GET/ServiceProviderConfig, /ResourceTypes, /SchemasyokKimlik 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ğiHermetry’de
idBu kuruluştaki üye kimliği
userName, birincil emails değeriHesap e-postası
externalIdÜye sayfasındaki SCIM harici kimliği (en fazla 256 karakter)
activeÜye durumu: true Etkin, false Etkin değil
name, displayNameAdları 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ı

DurumscimTypeNe zaman
400invalidFilteruserName eq veya externalId eq dışındaki bir filtre
400invalidSyntax, invalidValueJSON olmayan veya şemayı bozan bir gövde
401yok“Invalid bearer token.”: belirteç bilinmiyor, süresi dolmuş, başka bir kuruluşa ait veya kapsamı eksik
404yokKuruluşunuzda bu kimliğe sahip üye yok
409uniquenessE-posta alınmış, ya da hesap var ama üye değil
412yokIf-Match, üyenin mevcut ETag değeriyle eşleşmiyor
429yok“Too many requests. Please slow down.”
501yokGruplar 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):

OlayGönderildiği zaman
member.created, member.updated, member.deletedBir üye eklendiğinde, değiştiğinde veya kaldırıldığında
invitation.sent, invitation.accepted, invitation.declined, invitation.revokedBir davetin durumu değiştiğinde
scim.user.provisioned, scim.user.updated, scim.user.deprovisionedKimlik sağlayıcınız bir üyeyi SCIM üzerinden değiştirdiğinde