Yetkilendirme kodu akışı ve PKCE

Flextell API’sine bir kullanıcı adına erişmenin yolu yetkilendirme kodu akışıdır. Uygulamanız kullanıcıyı Flextell’in giriş ve onay ekranına gönderir, geri dönen tek kullanımlık kodu access_token ile değiştirir. Bu sayfa akışı PKCE ile birlikte, istek istek anlatır. Başlamadan önce bir uygulamanız ve kayıtlı bir redirect_uri değeriniz olmalı. Bunun için Uygulama oluşturma sayfasına bakın. Örneklerde üretim adresleri kullanılır; sandbox için Ortamlar sayfasındaki adresleri kullanın.

Akışa genel bakış

Akışta üç taraf vardır: kullanıcının tarayıcısı, sizin uygulamanız ve Flextell kimlik sunucusu (https://id.flextell.ai).

Adım	Ne olur
1	Uygulamanız `code_verifier` ve `code_challenge` üretir.
2	Tarayıcıyı `GET /oauth/authorize` adresine yönlendirirsiniz.
3	Kullanıcı giriş yapar, gerekirse iki adımlı doğrulamayı geçer ve onay ekranında Erişim İzni Ver’e tıklar.
4	Kimlik sunucusu tarayıcıyı `redirect_uri?code=...&state=...` adresine yönlendirir.
5	Uygulamanız kodu `POST /oauth/token` ile token’a çevirir.

Kimlik sunucusunun adreslerini https://id.flextell.ai/.well-known/openid-configuration adresinden de okuyabilirsiniz. Ayrıntı için OpenID Connect sayfasına bakın.

PKCE değerlerini üretme

PKCE (Proof Key for Code Exchange), kodu ele geçiren bir üçüncü tarafın kodu kullanmasını engeller. Her yetkilendirme isteği için yeni bir çift üretin.

Değer	Kural
`code_verifier`	43–128 karakter; yalnızca `A-Z a-z 0-9 - . _ ~` karakterleri.
`code_challenge`	`code_verifier` değerinin SHA-256 özetinin padding’siz base64url hâli.
`code_challenge_method`	Her zaman `S256` gönderin. Göndermezseniz sunucu `plain` varsayar.

Aşağıdaki komutlar bir çift üretir:

CODE_VERIFIER=$(openssl rand -base64 64 | tr -d '\n=+/' | cut -c1-64)
CODE_CHALLENGE=$(printf '%s' "$CODE_VERIFIER" | openssl dgst -sha256 -binary | openssl base64 -A | tr '+/' '-_' | tr -d '=')

code_verifier değerini kullanıcının tarayıcısına veya URL’ye koymayın. Token isteğine kadar yalnızca uygulamanızın oturumunda saklayın. Genel (public) istemciler code_challenge göndermek zorundadır; göndermezse istek invalid_request ile reddedilir.

Yetkilendirme isteği

Kullanıcının tarayıcısını şu adrese yönlendirin:

https://id.flextell.ai/oauth/authorize?response_type=code&client_id=CLIENT_ID&redirect_uri=https%3A%2F%2Fexample.com%2Fcallback&scope=openid%20profile%20email%20account%3Aread%20customers%3Aread&state=STATE&nonce=NONCE&code_challenge=CODE_CHALLENGE&code_challenge_method=S256

Parametre	Zorunlu	Açıklama
`response_type`	Evet	Her zaman `code`. `token` (implicit) desteklenmez.
`client_id`	Evet	Uygulamanızın Client ID değeri.
`redirect_uri`	Evet	Uygulamada kayıtlı adreslerden biriyle birebir aynı olmalı. Yalnızca tek adres kayıtlıysa atlanabilir.
`scope`	Önerilir	Boşlukla ayrılmış scope listesi, örneğin `openid profile email customers:read`.
`state`	Önerilir	Sunucu bu değeri değiştirmeden geri döndürür. Her istekte rastgele üretin ve dönüşte karşılaştırın.
`code_challenge`	Genel istemcilerde evet, gizli istemcilerde önerilir	PKCE sınama değeri.
`code_challenge_method`	Önerilir	`S256`. Varsayılan `plain`’dir.
`nonce`	İsteğe bağlı	`openid` scope’u ile `id_token` alıyorsanız `id_token` içinde geri döner.
`prompt`	İsteğe bağlı	`none`, `login` veya `consent`.

prompt değerleri şöyle çalışır:

Değer	Davranış
`none`	Ekran göstermez. Açık oturum yoksa `login_required`, onay gerekiyorsa `consent_required` hatasıyla geri döner.
`login`	Mevcut oturumu sonlandırır ve giriş formunu bir kez zorlar.
`consent`	Onay ekranını her zaman gösterir.

Scope göndermezseniz token hiçbir scope taşımaz. Her scope, uygulamanız için tanımlı olmalıdır. İzin verilmeyen bir scope isterseniz kullanıcı hiçbir ekran görmeden error=invalid_scope ile redirect_uri adresine döner.

Onay ekranı

Kullanıcının Flextell oturumu yoksa önce Giriş Yap ekranı açılır. Hesapta iki adımlı doğrulama etkinse İki Adımlı Doğrulama ekranı da gelir. Giriş tamamlanınca kullanıcı otomatik olarak yetkilendirme isteğine döner; sizin bir şey yapmanız gerekmez. Ardından Yetkilendirme ekranı açılır. Ekran şunları gösterir:

Uygulamanızın adı ve “sizin adınıza aşağıdaki izinlere erişmek istiyor.” metni.
Kimlik bilgilerinize erişim bölümü: profile, email ve phone scope’larını Profil bilgileri, E-posta adresi ve Telefon numarası olarak listeler.
İstenen yetkiler bölümü: uygulama scope’larını kaynağa göre gruplar ve her birine okuma veya yazma rozeti koyar.
Erişim İzni Ver ve İptal Et düğmeleri.

Kullanıcı Erişim İzni Ver’e tıklarsa tarayıcı redirect_uri?code=...&state=... adresine döner. İptal Et’e tıklarsa redirect_uri?state=...&error=access_denied adresine döner. Onay ekranı her seferinde gösterilmez. Kullanıcının bu uygulama için, istenen scope’ları kapsayan geçerli bir token’ı varsa ekran atlanır. Flextell’in kendi uygulamaları için de ekran gösterilmez. prompt=consent ile ekranı zorlayabilirsiniz.

Dönen code 10 dakika geçerlidir ve yalnızca bir kez kullanılabilir. Aynı kodu ikinci kez gönderirseniz invalid_grant hatası alırsınız.

Kodu token ile değiştirme

Kodu POST https://id.flextell.ai/oauth/token adresine gönderin. İstek application/x-www-form-urlencoded biçimindedir; JSON gövde de kabul edilir.

Parametre	Zorunlu	Açıklama
`grant_type`	Evet	`authorization_code`.
`client_id`	Evet	Client ID.
`client_secret`	Gizli istemcilerde	Body’de gönderin ya da HTTP Basic kullanın. Genel (public) istemcilerde gönderilmez.
`redirect_uri`	Yetkilendirme isteğinde gönderdiyseniz	Yetkilendirme isteğindekiyle birebir aynı olmalı.
`code`	Evet	Callback adresinde aldığınız kod.
`code_verifier`	`code_challenge` gönderdiyseniz evet	Adım 1’de ürettiğiniz doğrulayıcı.

curl -X POST https://id.flextell.ai/oauth/token \
  -H "Accept: application/json" \
  -d grant_type=authorization_code \
  -d client_id=CLIENT_ID \
  -d client_secret=CLIENT_SECRET \
  -d redirect_uri=https://example.com/callback \
  -d code=CODE \
  -d code_verifier="$CODE_VERIFIER"

curl -X POST https://id.flextell.ai/oauth/token \
  -u "CLIENT_ID:CLIENT_SECRET" \
  -H "Accept: application/json" \
  -d grant_type=authorization_code \
  -d redirect_uri=https://example.com/callback \
  -d code=CODE \
  -d code_verifier="$CODE_VERIFIER"

Accept: application/json başlığını her zaman ekleyin; hatalar HTML yerine JSON döner. Başarılı yanıt:

{
  "scope": "openid profile email account:read customers:read",
  "id_token": "eyJ...",
  "token_type": "Bearer",
  "expires_in": 300,
  "access_token": "eyJ...",
  "refresh_token": "def50..."
}

Alan	Açıklama
`scope`	Gerçekte verilen scope’lar. İstediğinizden farklı olabilir; kontrol edin.
`id_token`	Yalnızca `openid` scope’u istediyseniz gelir.
`expires_in`	`access_token` ömrü, saniye cinsinden (yaklaşık 300).
`refresh_token`	Yeni `access_token` almak için kullanılır.

Token’ı API’de Authorization: Bearer <access_token> başlığıyla kullanın. Klinik verisi isteyen uç noktalar X-Tenant başlığı da ister; bkz. Klinikler ve X-Tenant. Token yenileme, ömürleri ve saklama için Token’lar sayfasına bakın.

Token isteği kimlik sunucusunda IP başına dakikada 60 istekle sınırlıdır. Yenileme isteklerini her API çağrısında değil, token süresi dolmadan önce bir kez yapın.

Sık yapılan hatalar

Hatalar {"error": "...", "error_description": "...", "hint": "..."} biçiminde JSON döner. Yetkilendirme isteğinde redirect_uri geçerliyse aynı alanlar yönlendirme adresinin sorgu dizesinde gelir. Tüm kodlar için Kimlik doğrulama hataları sayfasına bakın.

Hata	HTTP	Ne zaman	Çözüm
`invalid_request`	400	`client_id`, `code`, `code_verifier` veya `redirect_uri` eksik; PKCE değeri biçimi bozuk (`Code challenge must follow the specifications of RFC-7636.`); genel istemci `code_challenge` göndermedi; `code_challenge` yokken `code_verifier` gönderildi; kod başka bir istemciye verilmiş.	`hint` alanındaki parametreyi düzeltin.
`invalid_client`	401	İstemci bilinmiyor ya da iptal edilmiş; `client_secret` yanlış; `redirect_uri` kayıtlı değil.	Client ID, secret ve kayıtlı adresleri kontrol edin.
`invalid_grant`	400	Kodun süresi dolmuş (`Authorization code has expired`); kod daha önce kullanılmış (`Authorization code has been revoked`); `code_verifier` eşleşmiyor (`Failed to verify code_verifier.`).	Akışı baştan başlatın ve yeni bir PKCE çifti üretin.
`invalid_scope`	400 veya yönlendirme	Scope bilinmiyor ya da uygulamanıza tanımlı değil.	Uygulamanın İzinler adımını ve `scope` değerini kontrol edin.
`unsupported_grant_type`	400	`password` ya da `response_type=token` kullanıldı.	`authorization_code` kullanın.
`access_denied`	yönlendirme	Kullanıcı İptal Et’e tıkladı.	Kullanıcıya akışı yeniden başlatma seçeneği sunun.
`login_required`	yönlendirme	`prompt=none` iken açık oturum yok.	`prompt` olmadan yeniden deneyin.
`consent_required`	yönlendirme	`prompt=none` iken onay gerekiyor.	`prompt` olmadan yeniden deneyin.

Redirect adresi uyuşmuyor

redirect_uri, uygulamada kayıtlı bir adresle birebir aynı olmalıdır; sondaki /, http ile https farkı ve sorgu dizesi de önemlidir. Kayıtlı adres yoksa istek invalid_client ile reddedilir ve kullanıcı yönlendirilmez. Token isteğinde de aynı adresi göndermelisiniz.

state değeri uyuşmuyor

Callback’teki state, yetkilendirme isteğinde gönderdiğinizle aynı değilse kodu kullanmayın. Bu, isteğin sizin başlattığınız akıştan gelmediği anlamına gelir.

Token alıyorum ama API 401 veya 403 dönüyor

401 token’ın süresinin dolduğunu ya da iptal edildiğini gösterir; refresh token ile yenileyin. 403 ve Invalid scope(s) provided. yanıtı, token’da gereken scope’un olmadığını gösterir; scope’u ekleyip kullanıcıyı yeniden yetkilendirin. Klinik uç noktalarında X-Tenant başlığını unutmayın.

İlgili sayfalar

Uygulama oluşturma

Client ID, secret ve redirect adreslerini tanımlayın.

Token'lar

Token ömürleri, yenileme ve iptal.

Scope'lar

İsteyebileceğiniz scope’lar ve gerektirdiği izinler.

Hatalar

Kimlik doğrulama hata kodlarının tam listesi.

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

Yetkilendirme kodu akışı ve PKCE

Akışa genel bakış

PKCE değerlerini üretme

Yetkilendirme isteği

Onay ekranı

Kodu token ile değiştirme

Sık yapılan hatalar

İlgili sayfalar

Uygulama oluşturma

Token'lar

Scope'lar

Hatalar

​Akışa genel bakış

​PKCE değerlerini üretme

​Yetkilendirme isteği

​Onay ekranı

​Kodu token ile değiştirme

​Sık yapılan hatalar

​İlgili sayfalar

Uygulama oluşturma

Token'lar

Scope'lar

Hatalar

Akışa genel bakış

PKCE değerlerini üretme

Yetkilendirme isteği

Onay ekranı

Kodu token ile değiştirme

Sık yapılan hatalar

İlgili sayfalar