> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flextell.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# OAuth uygulamaları

> OAuth uygulamalarını API ile listelemeyi, oluşturmayı, scope güncellemeyi ve iptal etmeyi anlatır.

OAuth uygulaması, entegrasyonunuzun Flextell API'sine erişmek için kullandığı kimliktir (Client ID ve Client Secret). Bu sayfa, uygulamaları `/api/v1/oauth/clients` endpoint'leriyle yönetmeyi anlatır. Erişim token'ı alma akışı için [Yetkilendirme kodu ve PKCE](/api/kimlik-dogrulama/yetkilendirme-kodu-ve-pkce) sayfasına bakın.

<Info>
  Uygulamalar **kullanıcıya aittir**, kliniğe ait değildir. Bir uygulamayı yalnızca onu oluşturan kullanıcı listeleyebilir ve yönetebilir. Aynı klinikteki iş arkadaşlarınız uygulamanızı göremez.
</Info>

## Endpoint özeti

Tüm isteklerde `Authorization: Bearer <access_token>` ve `X-Tenant: <tenant_id>` başlıkları zorunludur. `X-Tenant` olmadan istek `400 TENANT_HEADER_REQUIRED` hatası verir ve izin yalnızca `X-Tenant` ile seçtiğiniz kliniğde kontrol edilir. Ayrıntı için [Klinikler ve X-Tenant](/api/klinikler-ve-x-tenant) sayfasına bakın.

| Metot | Endpoint | Açıklama | Scope | İzin |
| - | - | - | - | - |
| `GET` | `/api/v1/oauth/clients` | Uygulamalarınızı listeler | `oauth_clients:read` | `View:Client` |
| `POST` | `/api/v1/oauth/clients` | Uygulama oluşturur | `oauth_clients:write` | `Create:Client` |
| `GET` | `/api/v1/oauth/clients/{id}` | Tek uygulamayı getirir | `oauth_clients:read` | `View:Client` |
| `PUT` | `/api/v1/oauth/clients/{id}` | Ad ve yönlendirme URI'lerini günceller | `oauth_clients:write` | `Update:Client` |
| `PUT` | `/api/v1/oauth/clients/{id}/scopes` | Scope listesini değiştirir | `oauth_clients:write` | `UpdateScopes:Client` |
| `POST` | `/api/v1/oauth/clients/{id}/secret` | Client Secret'ı yeniler | `oauth_clients:write` | `Update:Client` |
| `POST` | `/api/v1/oauth/clients/{id}/revoke` | Uygulamanın erişimini iptal eder | `oauth_clients:write` | `Revoke:Client` |
| `POST` | `/api/v1/oauth/clients/{id}/activate` | İptal edilmiş uygulamayı yeniden etkinleştirir | `oauth_clients:write` | `Activate:Client` |
| `DELETE` | `/api/v1/oauth/clients/{id}` | Uygulamayı siler | `oauth_clients:write` | `Delete:Client` |
| `GET` | `/api/v1/oauth/clients/{id}/tokens` | Uygulama için verilmiş access token'ları listeler | `oauth_clients:read` | `View:Client` |
| `DELETE` | `/api/v1/oauth/clients/{id}/tokens` | Uygulamanın tüm access token'larını iptal eder | `oauth_clients:write` | `Revoke:Client` |
| `GET` | `/api/v1/oauth/scopes` | Bir uygulamanın isteyebileceği scope'ları listeler | `oauth_clients:read` | `View:Client` |

Kullanılabilir scope'ların tam listesi için [Scope'lar](/api/kimlik-dogrulama/scopelar) sayfasına bakın.

<Note>
  Başka bir kullanıcıya ait uygulamalar, Flextell'in kendi uygulamaları ve kliniğe bağlı uygulamalar için `{id}` istekleri `403` değil `404 RESOURCE_NOT_FOUND` döndürür. Böylece bu uygulamaların var olup olmadığı sızdırılmaz. UUID olmayan bir `{id}` de `404` verir.
</Note>

## Nesne modeli

Uygulama yanıtları (`OAuthClientResource`) şu alanları içerir:

| Alan | Tür | Açıklama |
| - | - | - |
| `id` | string (UUID) | Client ID. |
| `name` | string | Uygulama adı. |
| `redirect_uris` | string\[] | Yetkilendirme sonrası yönlendirme URI'leri. |
| `post_logout_redirect_uris` | string\[] | Çıkış sonrası yönlendirme URI'leri. |
| `scopes` | nesne\[] | Uygulamaya tanınan scope'lar, her biri `{scope, description}`. |
| `grant_types` | string\[] | API ile oluşturulan uygulamalarda her zaman `["authorization_code","refresh_token"]`. |
| `revoked` | boolean | Erişim iptal edilmişse `true`. |
| `tokens_count` | integer | Uygulama için verilmiş token sayısı. |
| `created_at`, `updated_at` | string | ISO 8601 zaman damgası. |

`secret` alanı yalnızca oluşturma ve yenileme yanıtlarında (`OAuthClientSecretResource`) bulunur.

<Warning>
  `secret` düz metin olarak yalnızca bu yanıtta döner ve sonradan okunamaz. Güvenli bir yerde saklayın. Kaybederseniz `POST /api/v1/oauth/clients/{id}/secret` ile yenileyin.
</Warning>

API ile oluşturulan uygulamalar her zaman gizli (confidential) istemcidir ve `authorization_code` ile `refresh_token` akışlarını kullanır. Kod değişimi, Client Secret'ı saklayabileceğiniz bir sunucuda yapılmalıdır.

### Listeleme

`GET /api/v1/oauth/clients` sayfalanmış bir liste döndürür (genel kurallar için [Sayfalama](/api/istekler/sayfalama) ve [Filtreleme ve sıralama](/api/istekler/filtreleme-ve-siralama)). Bu kaynağa özgü parametreler:

| Parametre | Açıklama |
| - | - |
| `search` | Uygulama adında arar (en çok 255 karakter). |
| `per_page` | 1–100 arası. Varsayılan 15. |
| `page` | Sayfa numarası. |
| `sort_by` | `name`, `revoked`, `created_at` veya `updated_at`. Varsayılan `created_at`. |
| `sort_order` | `asc` veya `desc`. Varsayılan `desc`. |
| `revoked` | `true` veya `false`. İptal durumuna göre süzer. |
| `created_at_from`, `created_at_to` | Oluşturulma tarihi aralığı. |
| `updated_at_from`, `updated_at_to` | Güncellenme tarihi aralığı. |

## Oluşturma

`POST /api/v1/oauth/clients` isteği şu alanları alır:

| Alan | Zorunlu | Kural |
| - | - | - |
| `name` | Evet | En çok 255 karakter. |
| `redirect_uris` | Evet | 1–20 URL, her biri en çok 2048 karakter. |
| `post_logout_redirect_uris` | Hayır | En çok 20 URL, her biri en çok 2048 karakter. |
| `scopes` | Evet | En az 1 uygulama scope'u. |

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST https://app.flextell.ai/api/v1/oauth/clients \
    -H "Authorization: Bearer <access_token>" \
    -H "X-Tenant: <tenant_id>" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Örnek Entegrasyon",
      "redirect_uris": ["https://example.com/callback"],
      "post_logout_redirect_uris": ["https://example.com/logged-out"],
      "scopes": ["customers:read", "appointments:read", "account:read"]
    }'
  ```

  ```json Yanıt (201) theme={null}
  {
    "success": true,
    "data": {
      "id": "<client_uuid>",
      "name": "Örnek Entegrasyon",
      "secret": "<40 karakterlik secret, yalnızca bir kez gösterilir>",
      "grant_types": ["authorization_code", "refresh_token"],
      "revoked": false
    }
  }
  ```
</CodeGroup>

Kurallar:

* URI'ler kırpılır ve boş girdiler atlanır. Her URI geçerli bir URL olmalıdır (`http`, `https` gibi bir şema ve host). `localhost:3000` gibi tek etiketli host'lar kabul edilir.
* `myapp://callback` gibi özel uygulama şemaları REST API'de `422` ile reddedilir.
* `scopes` içine yalnızca etkin uygulama scope'ları yazılır. `openid`, `profile`, `email` ve `phone` listeye yazılmaz; her uygulama bunları zaten isteyebilir.
* Geçerli scope'ları `GET /api/v1/oauth/scopes` ile alın. Yanıt, `scope` alanına göre sıralı `{scope, description}` listesidir.

`PUT /api/v1/oauth/clients/{id}` ile `name`, `redirect_uris` ve `post_logout_redirect_uris` alanlarını güncelleyebilirsiniz. Alanların hepsi isteğe bağlıdır. Gönderdiğiniz liste eskisinin yerine geçer; `post_logout_redirect_uris` için boş liste (`[]`) gönderebilirsiniz.

## Scope güncelleme

`PUT /api/v1/oauth/clients/{id}/scopes` uygulamanın scope listesini tamamen değiştirir. `scopes` zorunludur ve en az bir eleman içermelidir. Mevcut listeye ekleme yapmak için eski scope'ları da gönderin.

```bash curl theme={null}
curl -X PUT https://app.flextell.ai/api/v1/oauth/clients/<client_uuid>/scopes \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Tenant: <tenant_id>" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"scopes": ["customers:read", "customers:write"]}'
```

<Note>
  Yeni liste yeni yetkilendirmelere ve token yenilemelere hemen uygulanır. Listeden çıkardığınız bir scope için `/oauth/authorize` isteği `invalid_scope` hatası verir. Yenileme sırasında bu scope'lar sessizce düşer. Daha önce verilmiş access token'lar süreleri dolana kadar eski scope'larıyla çalışır.
</Note>

## İptal ve silme

Üç farklı işlem vardır. Etkileri farklıdır.

| İşlem | Endpoint | Etkisi | Geri alınır mı |
| - | - | - | - |
| Token'ları iptal etme | `DELETE /api/v1/oauth/clients/{id}/tokens` | Yalnızca etkin access token'ları iptal eder. Uygulama etkin kalır. Yanıtta `revoked_tokens_count` döner. | Hayır |
| Uygulamayı iptal etme | `POST /api/v1/oauth/clients/{id}/revoke` | Uygulamayı (`revoked: true`) ve tüm access token'larını iptal eder. | Evet, `activate` ile |
| Silme | `DELETE /api/v1/oauth/clients/{id}` | Uygulamayı access token'ları, refresh token'ları ve yetkilendirme kodlarıyla birlikte kalıcı olarak siler. | Hayır |

`POST /api/v1/oauth/clients/{id}/activate` iptal edilmiş uygulamayı `revoked: false` durumuna getirir. Bu işlem uygulamanın access token'larını da yeniden etkin yapar.

`POST /api/v1/oauth/clients/{id}/secret` yeni bir 40 karakterlik secret üretir ve yanıtta bir kez gösterir. Eski secret token endpoint'inde çalışmaz; mevcut token'lar geçerli kalır.

`GET /api/v1/oauth/clients/{id}/tokens` uygulamayı yetkilendiren **tüm** kullanıcıların token'larını (yalnızca sizinkileri değil) en yeniden eskiye döndürür. Parametreler: `per_page` (1–100), `page`, `revoked`, `created_at_from`, `created_at_to`. Her kayıt şu alanları içerir: `id`, `client_id`, `user_id`, `name`, `scopes`, `revoked`, `created_at`, `updated_at`, `expires_at`.

## Hatalar

Hatalar standart yanıt zarfıyla döner. Genel hata kodları için [Hata kodları](/api/istekler/hata-kodlari) sayfasına bakın.

| Kod | HTTP | Ne zaman |
| - | - | - |
| `TENANT_HEADER_REQUIRED` | 400 | `X-Tenant` başlığı yok. |
| `UNAUTHENTICATED` | 401 | Token yok, geçersiz, süresi dolmuş veya iptal edilmiş. |
| `FORBIDDEN` | 403 | Token'da gerekli scope yok veya seçili kliniğde ilgili `*:Client` izniniz yok. |
| `RESOURCE_NOT_FOUND` | 404 | Uygulama yok, size ait değil, Flextell'in kendi uygulaması veya kliniğe bağlı. Mesaj: `OAuth uygulaması bulunamadı`. |
| `TENANT_NOT_FOUND` | 404 | `X-Tenant` geçersiz veya o kliniğe üye değilsiniz. |
| `OAUTH_SCOPE_INVALID` | 422 | Oluşturma veya scope güncellemede bilinmeyen, devre dışı ya da OpenID scope'u var. `data.invalid_scopes` geçersiz scope'ları listeler. Mesaj: `İstenen kapsamlardan biri veya birkaçı geçersiz.` |
| `OAUTH_CLIENT_ALREADY_REVOKED` | 422 | Zaten iptal edilmiş uygulama yeniden iptal edildi. Mesaj: `Bu uygulamanın erişimi zaten kaldırılmış.` |
| `OAUTH_CLIENT_NOT_REVOKED` | 422 | Zaten etkin olan uygulama etkinleştirilmek istendi. Mesaj: `Bu uygulama zaten aktif.` |
| `VALIDATION_FAILED` | 422 | Alan kuralları ihlal edildi (ör. geçersiz URL, boş `scopes`). Mesaj: `Gönderilen veriler geçersiz.` |

Örnek `OAUTH_SCOPE_INVALID` yanıtı:

```json Yanıt (422) theme={null}
{
  "success": false,
  "error_code": "OAUTH_SCOPE_INVALID",
  "message": "İstenen kapsamlardan biri veya birkaçı geçersiz.",
  "data": { "invalid_scopes": ["ornek:scope"] }
}
```

<Note>
  Uygulama izinlerini rol editöründe **OAuth Uygulamaları** grubunda verirsiniz (ör. `Create:Client` için **Oluştur**, `Revoke:Client` için **Erişimi İptal Et**). Genel izin modeli için [İzinler ve görünürlük](/api/izinler-ve-gorunurluk) sayfasına bakın.
</Note>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.