OAuth uygulamaları

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 sayfasına bakın.

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.

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 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 sayfasına bakın.

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.

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.

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.

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 ve Filtreleme ve sıralama). 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.

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"]
  }'

{
  "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
  }
}

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.

curl

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"]}'

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.

İ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ı 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ı:

Yanıt (422)

{
  "success": false,
  "error_code": "OAUTH_SCOPE_INVALID",
  "message": "İstenen kapsamlardan biri veya birkaçı geçersiz.",
  "data": { "invalid_scopes": ["ornek:scope"] }
}

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 sayfasına bakın.

Başlarken

Kimlik Doğrulama

Çok Kiracılılık

İstek Kuralları

Kaynak Rehberleri

Gerçek Zamanlı

Webhook'lar ve Açık Uçlar

Entegrasyonlar

Rehberler

Kaynaklar

OAuth uygulamaları

Endpoint özeti

Nesne modeli

Listeleme

Oluşturma

Scope güncelleme

İptal ve silme

Hatalar

​Endpoint özeti

​Nesne modeli

​Listeleme

​Oluşturma

​Scope güncelleme

​İptal ve silme

​Hatalar

Endpoint özeti

Nesne modeli

Listeleme

Oluşturma

Scope güncelleme

İptal ve silme

Hatalar