Kuruluş rolünü al

GET /fapi/v1/organizations/{org_id}/roles/{role_id} · ortamın oturum açma ana bilgisayarından çağrılır

Kuruluşun bir rolünü veya kuruluş yöneticilerinin atayabileceği bir ortam rolünü döndürür. Kimliği doğrulanmış kullanıcının __Host-idp_session çerezi gereklidir; çerez yoksa, süresi dolmuşsa veya iptal edilmişse 401 unauthenticated döndürülür. Farklı bir kökendeki birinci taraf bir uygulama bunun yerine ön yüz API erişim belirtecini gönderebilir (Authorization: DPoP <token> ile bir DPoP kanıtı; bkz. Ön yüz API erişim belirteci). Kullanıcı, kuruluşun aktif bir üyesi olmalı ve idp_roles:manage iznine sahip olmalıdır. Üye olmayan bir kullanıcı 404 not_found alır; böylece kuruluşun varlığı açığa çıkmaz. İzni olmayan bir üye 403 insufficient_permissions alır. Kuruluş rolleri ortam için etkinleştirilmiş ve planına dahil edilmiş olmalıdır.

İstek

Üstbilgiler:

Üstbilgi Zorunlu Açıklama
Idp-Client evet SDK tanımlayıcısı.

org_id: kuruluş tanımlayıcısı (org_…). role_id: rol tanımlayıcısı (rol_…).

Gövde yok.

Yanıt

200 OK, ETag üstbilgisiyle ("<version>"):

Alan Tür Açıklama
id string Rol tanımlayıcısı (rol_…).
organization_id string veya null Kuruluş tanımlayıcısı (org_…); kuruluşta atanmak üzere sunulan bir ortam rolü için null (burada yalnızca okunur).
key string Rol anahtarı; kuruluş içinde ve ortam rolleri arasında benzersizdir; asla değişmez.
name string Görünen ad.
description string Açıklama; ayarlanmamışsa boştur.
is_privileged boolean Rolün yönetici izinleri verip vermediği.
assignable_in_self_service boolean Kuruluş yöneticilerinin rolü atayıp atayamayacağı.
permission_ids string[] İzin tanımlayıcıları (perm_…).
created_at string RFC 3339, UTC.
updated_at string RFC 3339, UTC.
version integer Geçerli sürüm; ETag üstbilgisi olarak da gönderilir ("<version>"). 
{
  "id": "rol_01jbz6x8kq3m2n4p5r6s7t8v9w",
  "organization_id": "org_01jbz6x8kq3m2n4p5r6s7t8v9a",
  "key": "auditor",
  "name": "Auditor",
  "description": "Read-only access to reports",
  "is_privileged": false,
  "assignable_in_self_service": true,
  "permission_ids": ["perm_01jbz6x8kq3m2n4p5r6s7t8v9b"],
  "created_at": "2026-10-28T09:30:00Z",
  "updated_at": "2026-10-28T09:30:00Z",
  "version": 1
}

Hatalar

Durum Kod Ne zaman
401 unauthenticated Geçerli oturum çerezi yok.
403 insufficient_permissions Kullanıcının kuruluşta idp_roles:manage izni yok.
403 plan_feature_unavailable Ortamın planı kuruluş rollerini içermiyor (feature, required_plan).
403 org_custom_roles_disabled Kuruluş rolleri ortam için kapalı.
404 not_found Bu kullanıcı için böyle bir kuruluş veya rol yok (bilinmeyen, hatalı biçimli veya başkasına ait bir tanımlayıcı aynı yanıtı verir).
503 service_unavailable Geçici olarak kullanılamıyor; Retry-After süresinden sonra yeniden deneyin.

Örnek

curl https://example.keenauth.app/fapi/v1/organizations/org_01jbz6x8kq3m2n4p5r6s7t8v9a/roles/rol_01jbz6x8kq3m2n4p5r6s7t8v9w \
  -H "Idp-Client: my-app/1.0.0 (node/22.0.0)" \
  -b cookies.txt