# 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](/docs/api/fapi/front-api-token)). 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>"`). |

```json
{
  "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

```bash
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
```