OAuth uygulaması oluşturma

Flextell API’sini kendi yazılımınızdan çağırmak için önce bir OAuth uygulaması kaydedersiniz. Kayıt size bir Client ID ve bir Client Secret verir. Bu sayfa uygulamayı nasıl oluşturacağınızı, yönlendirme adreslerini nasıl gireceğinizi ve gizli anahtarı nasıl saklayacağınızı anlatır. Oturum açma akışının kendisi için Yetkilendirme kodu ve PKCE sayfasına bakın.

Uygulamalar sizin kullanıcı hesabınıza aittir, kliniğe değil. Aynı kliniğin başka bir kullanıcısı uygulamanızı listede görmez. Başkasına ait bir uygulamanın kimliğini çağırırsanız 404 RESOURCE_NOT_FOUND alırsınız. Uygulamayı yetkilendiren her Flextell kullanıcısı, kendi rollerinin izin verdiği kliniklerde uygulamanızla işlem yapabilir.

Başlamadan önce

Bir klinikte Create:Client iznine sahip olmalısınız (rol editöründe Oluşturma). Panelde Uygulamalar sayfasını görmek için View:Client (Görüntüleme) gerekir.
Oluşturulan her uygulama gizli (confidential) bir istemcidir ve yalnızca authorization_code ile refresh_token akışlarını kullanır. Gizli anahtarı saklayabileceğiniz bir sunucu tarafı gerekir. Salt tarayıcı ya da mobil uygulama için gizli anahtarsız istemci kaydedemezsiniz.
API ile oluşturacaksanız elinizde oauth_clients:write scope’lu bir access token olmalı. Token almak için kayıtlı bir uygulama gerektiği için ilk uygulamayı panelden oluşturabilirsiniz.
/oauth/* çağrılarının tamamında X-Tenant başlığı zorunludur. Başlık yoksa 400 TENANT_HEADER_REQUIRED döner. İzin, yalnızca başlıkta verdiğiniz klinikte denetlenir. Ayrıntı için Klinikler ve X-Tenant sayfasına bakın.

Panelden oluşturma

Menü yolu: Bağlantılar → Uygulamalar. Panel sayfasının tamamı için Uygulamalar sayfasına bakın.

Sihirbazı açın

Bağlantılar → Uygulamalar sayfasında Uygulama Oluştur düğmesine tıklayın.

Uygulama bilgilerini girin

Uygulama Bilgileri adımında Uygulama Adı’nı (en fazla 255 karakter) ve en az bir Yönlendirme URI’leri satırını doldurun. Satır eklemek için URI Ekle, silmek için URI’yi Kaldır düğmesini kullanın. İsterseniz Çıkış Sonrası Yönlendirme URI’leri de ekleyin. İleri’ye tıklayın.

İzinleri seçin

İzinler adımında uygulamanın erişebileceği yetkileri işaretleyin. Arama kutusu ve Tümünü Seç / Tümünü Kaldır düğmesi vardır. En az bir izin seçmeden ilerleyemezsiniz. İleri’ye tıklayın.

Kimlik bilgilerini kopyalayın

Kimlik Bilgileri adımında Client ID ve Client Secret görünür. Her ikisini de kopyalama düğmesiyle alın ve güvenli bir yerde saklayın. Sonra Bitir’e tıklayın.

Panelde İzinler adımı, API’deki scopes alanına karşılık gelir. Yetkiler ve İzinler aynı şeyi anlatır. Uygulamayı ve scope atamasını panelden oluşturabilirsiniz. İzinler adımındaki ve Yetkileri Güncelle penceresindeki liste, seçili klinik için yüklenir. Klinik değiştirdiğinizde liste yeniden yüklenir. Liste yüklenemezse Yetki listesi yüklenemedi. iletisi görünür. Otomasyon için API adımları aşağıdadır.

API ile oluşturma

POST /api/v1/oauth/clients uygulamayı oluşturur ve 201 ile döner.

Metot	Endpoint	Açıklama	Scope	İzin
`GET`	`/oauth/clients`	Uygulamalarınızı listeler	`oauth_clients:read`	`View:Client`
`POST`	`/oauth/clients`	Uygulama oluşturur	`oauth_clients:write`	`Create:Client`
`GET`	`/oauth/scopes`	Uygulamaya atanabilecek scope’ları listeler	`oauth_clients:read`	`View:Client`

Gövde alanları:

Alan	Tür	Zorunlu	Kural
`name`	string	Evet	En fazla 255 karakter
`redirect_uris`	string[]	Evet	1–20 adres; her biri geçerli bir URL, en fazla 2048 karakter
`post_logout_redirect_uris`	string[]	Hayır	En fazla 20 adres; her biri geçerli bir URL, en fazla 2048 karakter
`scopes`	string[]	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": ["account:read", "customers:read", "appointments:read"]
  }'

{
  "success": true,
  "data": {
    "id": "<client_id>",
    "name": "Örnek Entegrasyon",
    "secret": "<40 karakterlik gizli anahtar>",
    "redirect_uris": ["https://example.com/callback"],
    "post_logout_redirect_uris": ["https://example.com/logged-out"],
    "scopes": [{ "scope": "account:read", "description": "Hesap bilgilerini okuma" }],
    "grant_types": ["authorization_code", "refresh_token"],
    "revoked": false
  }
}

Yanıttaki id değeri Client ID’dir. Yanıt ayrıca tokens_count, created_at ve updated_at alanlarını da içerir.

account:read scope’unu listeye ekleyin. Hangi kliniklere erişebildiğinizi öğrenmek için kullanacağınız /account/tenants çağrısı bu scope’u ister.

Yönlendirme adresleri

redirect_uris, kullanıcı yetkilendirmeyi tamamladıktan sonra Flextell’in kullanıcıyı geri gönderebileceği adreslerdir. post_logout_redirect_uris ise oturum kapatıldıktan sonra dönülebilecek isteğe bağlı adreslerdir.

Adresler kırpılır, boş girişler atılır.
Her adres Laravel’in url kuralından geçmelidir. https://example.com/callback ve http://localhost:3000/callback gibi adresler kabul edilir.
Özel uygulama şemaları (myapp://callback) REST API’de 422 ile reddedilir.
Eşleşme birebirdir. Yetkilendirme isteğinde gönderdiğiniz redirect_uri, kayıtlı adreslerden biriyle karakter karakter aynı olmalıdır. Sondaki /, http ile https farkı ya da fazladan bir yol eşleşmeyi bozar.
http://127.0.0.1 ve http://[::1] adreslerinde port farkı yok sayılır. http://localhost için böyle bir istisna yoktur.
Kayıtlı olmayan bir adrese yönlendirme yapılmaz. İstek 401 ve invalid_client ile döner.
Tek bir adres kaydettiyseniz yetkilendirme isteğinde redirect_uri göndermeyebilirsiniz. Gönderdiyseniz token isteğinde de aynen göndermeniz gerekir.

Adresleri değiştirmek için PUT /api/v1/oauth/clients/{id} kullanın (Update:Client, scope oauth_clients:write). Gönderdiğiniz liste eskisinin yerine geçer. Yalnızca gönderdiğiniz alanlar güncellenir. Çıkış adreslerini temizlemek için post_logout_redirect_uris alanına [] gönderin. Panelde aynı işlem satır menüsündeki Düzenle ile yapılır. Bu pencerede yalnızca ad ve adresler değişir.

Gizli anahtar

Gizli anahtar (secret) 40 karakterlik rastgele bir değerdir. Yalnızca uygulamayı oluşturduğunuz yanıtta ve yenilediğiniz yanıtta görünür. Flextell anahtarı özetlenmiş (hash) biçimde saklar, bu yüzden sonradan okuyamaz.

Client Secret yalnızca bir kez gösterilir. Hemen bir parola yöneticisine ya da sunucunuzun gizli değişken deposuna kaydedin. Anahtarı tarayıcı koduna, mobil uygulamaya veya herkese açık bir depoya koymayın.

Token uç noktasında anahtarı client_secret olarak gövdede ya da HTTP Basic ile gönderirsiniz. Anahtarı göndermezseniz 400 invalid_request, yanlış gönderirseniz 401 invalid_client alırsınız. Ayrıntı için Yetkilendirme kodu ve PKCE sayfasına bakın.

Anahtarı kaybettiyseniz

POST /api/v1/oauth/clients/{id}/secret yeni bir 40 karakterlik anahtar üretir. İzin Update:Client, scope oauth_clients:write. Yanıt, yeni anahtarı yine yalnızca bir kez gösterir.

Eski anahtar token uç noktasında hemen çalışmaz hâle gelir.
Daha önce verilmiş token’lar geçerliliğini korur.
Panelde anahtarı yenileme düğmesi yoktur. Bu işlemi yalnızca API ile yaparsınız.

Scope atama

Uygulamanın isteyebileceği scope’lar, oluşturma sırasında scopes alanında belirlenir. Atanabilecek scope’ların güncel listesini GET /api/v1/oauth/scopes döndürür ({scope, description}, scope’a göre sıralı). Tüm scope’ların anlamı için Scope’lar sayfasına bakın. Atamayı sonradan değiştirmek için PUT /api/v1/oauth/clients/{id}/scopes kullanın. İzin UpdateScopes:Client (Kapsamları güncelleme), scope oauth_clients:write. Gönderdiğiniz liste tamamını değiştirir.

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

Panelde aynı işlemi satır menüsündeki Yetkileri Güncelle açar. Açılan pencerede mevcut seçimler işaretli gelir. Güncelle’ye tıklayın.

Kural	Sonuç
Listede en az bir scope olmalı	Aksi hâlde `422` doğrulama hatası
Her giriş etkin bir uygulama scope’u olmalı	Aksi hâlde `422 OAUTH_SCOPE_INVALID`; geçersiz olanlar `data.invalid_scopes` içinde döner
`openid`, `profile`, `email`, `phone` listeye yazılmaz	Bu dört scope her uygulama için zaten serbesttir; listeye yazarsanız `OAUTH_SCOPE_INVALID` alırsınız
Değişiklik yeni yetkilendirmelere hemen uygulanır	Listeden çıkardığınız bir scope’u isteyen yetkilendirme `invalid_scope` ile reddedilir; yenileme isteklerinde ise sessizce düşer
Mevcut access token’lar	Süreleri bitene kadar (5 dakika) eski scope’larıyla çalışır

Bir isteğin gerçek yetkisi üç şeyin kesişimidir: token’daki scope, kullanıcının o klinikteki izinleri ve kullanıcının klinik üyeliği. Uygulamaya geniş scope vermek, kullanıcının sahip olmadığı bir izni açmaz.

Uygulamayı iptal etme

İptal, uygulamanın erişimini geri alınabilir biçimde keser. Silme ise uygulamayı kaldırır.

İşlem	Endpoint	İzin	Sonuç
İptal et	`POST /oauth/clients/{id}/revoke`	`Revoke:Client` (Erişimi kaldırma)	Uygulama ve tüm access token’ları iptal olur. Uygulama yeni yetkilendirme alamaz, token yenileyemez, API çağrıları `401` döner.
Etkinleştir	`POST /oauth/clients/{id}/activate`	`Activate:Client` (Aktifleştirme)	Uygulama yeniden etkin olur.
Token’ları iptal et	`DELETE /oauth/clients/{id}/tokens`	`Revoke:Client`	Yalnızca etkin access token’ları iptal eder; uygulama etkin kalır. Yanıtta `revoked_tokens_count` döner.
Sil	`DELETE /oauth/clients/{id}`	`Delete:Client` (Silme)	Uygulama; token’ları ve yetkilendirme kodlarıyla birlikte silinir.

Hepsi oauth_clients:write scope’u ister. Zaten iptal edilmiş bir uygulamayı iptal etmek 422 OAUTH_CLIENT_ALREADY_REVOKED (Bu uygulamanın erişimi zaten kaldırılmış.), etkin bir uygulamayı etkinleştirmek 422 OAUTH_CLIENT_NOT_REVOKED (Bu uygulama zaten aktif.) döndürür. Panelde satır menüsünde etkin uygulama için İptal Et, iptal edilmiş uygulama için Etkinleştir, her ikisi için Sil vardır. Her işlem bir onay penceresi açar. Listede Aktiflik sütunu Aktif ya da Pasif gösterir. Panelde İptal Et, uygulamayı silmez; yalnızca erişimini kaldırır.

Etkinleştir, uygulamanın daha önce verdiği access token’ları da yeniden etkinleştirir. Bunlara, ayrı ayrı iptal edilmiş olanlar da dahildir. Şüpheli bir uygulamayı yeniden etkinleştirmeden önce bunu hesaba katın. Erişimi kalıcı olarak kesmek istiyorsanız uygulamayı silin. Token türleri için Token’lar sayfasına bakın.

GET /oauth/clients/{id}/tokens uygulama için verilmiş access token’ları (tüm kullanıcılar dahil) en yeniden eskiye listeler. Diğer uç noktaların şemaları için OAuth uygulamaları sayfasına bakın.

Hatalar

Kod	HTTP	Ne zaman
`TENANT_HEADER_REQUIRED`	400	`X-Tenant` başlığı gönderilmedi
`FORBIDDEN`	403	Token’da `oauth_clients:` scope’u ya da klinikte ilgili `:Client` izni yok
`RESOURCE_NOT_FOUND`	404	Uygulama yok ya da size ait değil (`OAuth uygulaması bulunamadı`)
`OAUTH_SCOPE_INVALID`	422	Listede bilinmeyen, pasif ya da OIDC scope’u var
`OAUTH_CLIENT_ALREADY_REVOKED`	422	İptal edilmiş uygulama yeniden iptal edildi
`OAUTH_CLIENT_NOT_REVOKED`	422	Etkin uygulama etkinleştirilmeye çalışıldı

Genel hata yapısı için Kimlik doğrulama hataları sayfasına bakın.

İlgili sayfalar

Yetkilendirme kodu ve PKCE

Kayıtlı uygulamanızla kullanıcı adına token alın.

Scope'lar

Atayabileceğiniz scope’ların listesi.

Token'lar

Access token, refresh token ve süreleri.

Uygulamalar (panel)

Panel ekranının ayrıntılı anlatımı.

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 uygulaması oluşturma

Başlamadan önce

Panelden oluşturma

API ile oluşturma

Yönlendirme adresleri

Gizli anahtar

Anahtarı kaybettiyseniz

Scope atama

Uygulamayı iptal etme

Hatalar

İlgili sayfalar

Yetkilendirme kodu ve PKCE

Scope'lar

Token'lar

Uygulamalar (panel)

​Başlamadan önce

​Panelden oluşturma

​API ile oluşturma

​Yönlendirme adresleri

​Gizli anahtar

​Anahtarı kaybettiyseniz

​Scope atama

​Uygulamayı iptal etme

​Hatalar

​İlgili sayfalar

Yetkilendirme kodu ve PKCE

Scope'lar

Token'lar

Uygulamalar (panel)

Başlamadan önce

Panelden oluşturma

API ile oluşturma

Yönlendirme adresleri

Gizli anahtar

Anahtarı kaybettiyseniz

Scope atama

Uygulamayı iptal etme

Hatalar

İlgili sayfalar