Kuruluş rollerini listele

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

Kuruluşun kendi rollerini ve kuruluş yöneticilerinin atayabileceği ortam rollerini tanımlayıcıya göre sıralanmış olarak 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_…).

Sorgu parametreleri:

Parametre	Zorunlu	Açıklama
`limit`	hayır	Sayfa boyutu, 1 ile 100 arası; varsayılan 20.
`after`	hayır	Önceki sayfanın `next_after` değeri.

Gövde yok.

Yanıt

200 OK:

Alan	Tür	Açıklama
`data[]`	object[]	Roller; alanları Kuruluş rolünü al bölümünde açıklanmıştır.
`next_after`	string	Sonraki sayfa için `after` olarak gönderin; son sayfada bulunmaz.

{
  "data": [
    {
      "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
400	`invalid_cursor`	`after`, önceki bir sayfadan gelen bir rol tanımlayıcısı değil.
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).
422	`validation_failed`	`limit` aralık dışında.
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?limit=20 \
  -H "Idp-Client: my-app/1.0.0 (node/22.0.0)" \
  -b cookies.txt