DevHub
OAuth 2.0 / OpenID Connect

Kimlik Doğrulama Rehberi

Paraşüt API'sini kullanmak için kullanıcılardan yetki almanın adım adım açıklaması. Authorization Code akışı, token yönetimi ve 3 farklı entegrasyon yöntemi hakkında teknik detaylar.

Ortam:

Başlamadan Önce

CLIENT_IDBaşvurunuz tamamlandığında API Bilgilerim sayfasında gösterilir.
REDIRECT_URIBaşvuruda belirtilen geri dönüş adresi (en fazla 3). Başvurudan sonra değiştirilemez; değişiklik için yeni başvuru yapmanız gerekir.
CLIENT_SECRETConfidential client'larda API Bilgilerim sayfasında görüntülenir ve yenilenir. Yalnızca backend'inizde saklayın.
Staging client'ınız sizin için oluşturulan Paraşüt staging hesabına bağlıdır; hesap henüz oluşturulmadıysa API Bilgilerim sayfasından oluşturabilirsiniz. Bu hesap 6 ay sonra otomatik silinir.

İstemci Türü

Token isteklerinin nasıl doğrulanacağı istemcinizin türüne bağlıdır. İstemcinizin türünü API Bilgilerim sayfasında görebilirsiniz.

Confidential client (varsayılan)1

Yeni API istemcileri varsayılan olarak confidential client olarak oluşturulur. Token alma ve yenileme istekleri backend'inizden, PKCE'ye ek olarak client_secret ile yapılır.

Client secret başvuru tamamlama ekranında ve API Bilgilerim sayfasında maskeli olarak gösterilir; oradan görüntüleyip kopyalayabilir ve “Secret'ı Yenile” ile yenileyebilirsiniz. Secret e-posta ile gönderilmez.

Secret yenileme: CLIENT_SECRET değerinin sızdığından şüphelenirseniz API Bilgilerim sayfasındaki “Secret'ı Yenile” ile yeni bir secret oluşturun. Yeni secret oluşturulduğu anda eski secret hemen geçersiz olur; geçiş süresi yoktur. Eski secret ile yapılan token ve yenileme istekleri reddedilir, bu nedenle yeniledikten hemen sonra backend'inizdeki değeri güncelleyin. Daha önce alınmış access token'lar süreleri dolana kadar geçerli kalır.

¹ İstisna – public client: Backend'i olmayan ve client secret'ı güvenli biçimde saklayamayan mobil veya masaüstü uygulamalar başvuru sırasında public client talep edebilir. Public client'ın secret'ı olmaz; token alma ve yenileme son kullanıcının cihazında PKCE ile yapılır ve token isteklerinde client_secret gönderilmez. Daha önce oluşturulmuş istemciler public olarak kalır. ↩

Akışa Genel Bakış

1
Yönlendirme URL
2
Paraşüt Login
3
Consent Adımı
4
Code Gelir
5
Token Alınır
6
API Çağrısı

Yetkilendirmeyi Kim Başlatır?

Authorization Code akışını üç farklı şekilde başlatabilirsiniz. Kullanım senaryonuza göre en uygun yöntemi seçin.

1

“Paraşüt Hesabımı Bağla” Butonu

3. taraf uygulamanıza bir buton koyun. Kullanıcı tıkladığında siz authorization URL'si oluşturup tarayıcıyı Paraşüt login sayfasına yönlendirirsiniz.

En yaygın yöntem. Kullanıcı deneyimi üzerinde en yüksek kontrol sizdedir.
2

Paraşüt Uygulamalar Sayfası

Uygulamanız Paraşüt “Uygulamalar” sayfasında yayınlanıyorsa, kullanıcı “Kullanmaya Başla” seçeneğine tıkladığında Paraşüt, kullanıcıyı uygulamanızın /oauth/start (veya benzeri) ucuna deep-link ile yönlendirir. Uygulamanız bu noktadan itibaren 3. yöntemde anlatıldığı şekilde authorization URL'sini üretip akışı sürdürür.

PKCE ve state parametrelerinin güvenli yönetilebilmesi için OAuth 2.0/2.1 BCP, IdP-initiated akışları önermez. Bu nedenle authorization URL üretme adımı her zaman 3. taraf uygulama tarafında başlamalıdır.
3

Backend'den Doğrudan Yönlendirme

Uygulamanızın backend'inden authorization URL'si oluşturup kullanıcıyı doğrudan Paraşüt login ekranına yönlendirebilirsiniz.

Bu akışta authorization URL'sine kc_idp_hint=parasut parametresini ekleyerek kimlik sağlayıcı seçim ekranını atlayıp kullanıcıyı doğrudan Paraşüt giriş ekranına yönlendirebilirsiniz.

Standart OAuth 2.0 Authorization Code + PKCE akışıdır. Hangi yöntemle başlatılırsa başlatılsın, confidential client'larda token değişimi backend'inizde client_secret ile yapılır.

Adım Adım Akış

1

Authorization URL Oluştur ve Yönlendir

Kullanıcıyı aşağıdaki URL'ye yönlendirin. state parametresini CSRF koruması için rastgele üretip oturum ile eşleştirin.

Authorization URL
https://id.parasut.com/realms/parasut/protocol/openid-connect/auth
  ?client_id=CLIENT_ID
  &redirect_uri=REDIRECT_URI
  &response_type=code
  &scope=openid
  &state=RANDOM_STATE
  &code_challenge=BASE64URL_SHA256_CODE_VERIFIER
  &code_challenge_method=S256
  &kc_idp_hint=parasut  # opsiyonel
ParametreDeğerAçıklama
client_idCLIENT_IDSize verilen uygulama kimliği
redirect_uriREDIRECT_URIBaşvuruda kayıtlı geri dönüş adresi
response_typecodeAuthorization Code akışı için sabit
scopeopenidTalep edilen izin kapsamı
stateRANDOM_STATECSRF koruması için rastgele değer
code_challengeBASE64URL_SHA256_CODE_VERIFIERZorunlu. PKCE için code_verifier değerinin SHA-256 özeti (Base64url)
code_challenge_methodS256Zorunlu. Yalnızca S256 desteklenir
kc_idp_hintparasutOpsiyonel. Kimlik sağlayıcı seçim ekranını atlayıp doğrudan Paraşüt giriş ekranına yönlendirir.
PKCE: code_verifier olarak A-Z, a-z, 0-9, -, ., _, ~ karakterlerinden oluşan, en az 43 en fazla 128 karakterlik, yüksek entropili rastgele bir dize üretin (RFC 7636). code_challenge için code_verifier üzerinde SHA-256 uygulayıp çıktıyı Base64url (padding = olmadan) kodlayın. Token isteğinde aynı oturum için ürettiğiniz ham code_verifier değerini gönderin.
2

Kullanıcı Paraşüt Login'e yönlendirilir ve giriş yapması beklenir

Kullanıcı Paraşüt giriş ekranında e-posta ve şifresiyle kimlik doğrulaması yapar.

Paraşüt Giriş Ekranı
3

Consent Adımı

Giriş başarılıysa kullanıcıya uygulamanızın hangi verilere erişeceği gösterilir. Kullanıcı onayladığında akış devam eder.

OAuth Consent Ekranı
4

Authorization Code Gelir

Kullanıcı onayladıktan sonra tarayıcı, REDIRECT_URI'nize yönlendirilir ve URL'de code parametresi bulunur.

Gelen redirect URL örneği
https://uygulamaniz.com/callback
  ?code=QnJvYWRjYXN0T3BhcXVlQ29kZV8xMjM0NTY...
  &state=RANDOM_STATE
state parametresini oturumdaki değerle karşılaştırın. Eşleşmiyorsa isteği reddedin (CSRF koruması).
5

Code ile Access Token Al

Gelen code değerini token endpoint'ine göndererek access_token ve refresh_token alın. Bu adım PKCE ile yapılır. Yetkilendirme kodu, code_verifier ile token endpoint'inde access_token ve refresh_token'a çevrilir. Confidential client'larda istek backend'inizden client_secret ile birlikte gönderilir (public client için bkz. dipnot ¹).

curl — token exchange
curl -X POST https://id.parasut.com/realms/parasut/protocol/openid-connect/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "client_id=CLIENT_ID" \
  -d "client_secret=CLIENT_SECRET" \
  -d "code=RETURNED_CODE" \
  -d "redirect_uri=REDIRECT_URI" \
  -d "code_verifier=ORIGINAL_RANDOM_CODE_VERIFIER"
client_id ve client_secret değerlerini form alanı yerine HTTP Basic kimlik doğrulamasıyla da gönderebilirsiniz: Authorization: Basic BASE64(CLIENT_ID:CLIENT_SECRET). Bu durumda client_secret satırını istek gövdesinden çıkarın.
client_secret ve code_verifier değerlerini tarayıcıya, mobil uygulama paketine veya loglara koymayın.
Yanıt
{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXV...",
  "token_type": "Bearer",
  "expires_in": 7200,
  "refresh_token": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpX...",
  "refresh_expires_in": 2592000,
  "scope": "openid"
}
Yanıttaki expires_in ve refresh_expires_in değerleri token sürelerini saniye cinsinden verir. Bu süre dolmadan önce yenileme yapmanız önerilir.
6

API'yi Kullan

Aldığınız access_token'i tüm Paraşüt API isteklerindeAuthorization: Bearer header'ı olarak gönderin.

curl — örnek API isteği
curl -X GET "https://api.parasut.com/v4/{company_id}/sales_invoices" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Accept: application/json"
Kullanıcı yetkileri: Kullanıcı onayıyla alınan token, kullanıcının Paraşüt'te o şirketteki rolüyle sınırlıdır; yalnızca kullanıcının o şirket için yetkili olduğu işlemler yapılabilir. Rolün kapsamadığı isteklere 403 Forbidden yanıtı döner. Uygulamanız bu yanıtı ele almalı: kullanıcıya bu işlem için yetkisi olmadığını anlaşılır biçimde göstermeli ve isteği otomatik olarak tekrarlamamalıdır. Olağandışı sayıda 401 veya 403 yanıtı alan API istemcileri engellenebilir ve devre dışı bırakılabilir.
Genel bilgiler:
  • {company_id}, erişilmek istenen firmanın Paraşüt kayıt numarasıdır ve Paraşüt hesabında profil alanından veya uygulama adresinden elde edilebilir. Örneğin 115 numaralı firmanın müşteri/tedarikçi listesi için https://api.parasut.com/v4/115/contacts adresi kullanılır.
  • API entegrasyonunda kullanılan kullanıcının entegrasyon kurabilme izni olmalıdır. Bu rol ve diğer yetki rolleri çerçevesinde işlem yapılabilir; yetkisiz durumlarda HTTP 403 cevabı alırsınız.
  • Rate limit bilgileriniz başvuru yaptığınız pakete göre değişiklik gösterir. Paketiniz 10 saniyede kaç istek yapabileceğinizi, 1 ayda toplam ne kadar istek yapabileceğinizi ve hangi firmalar için işlem yapabileceğinizi belirler. Limitiniz dolduğunda HTTP 429 cevabı alırsınız; cevapta tekrar ne zaman istek yapabileceğinize dair süre bilgisi de bulunur.
Webhook'lar: Webhook uçlarını yalnızca Geliştirici Portalı'ndan alınmış ve API paketi webhook içeren bir API istemcisinin access token'ı ile çağırabilirsiniz; aksi halde istekler 403 döner. Ayrıntılar için Webhook rehberine bakın.

Token Yenileme

Token yanıtındaki expires_in değeri ne zaman yenilemeniz gerektiğini saniye cinsinden gösterir. Bu süre dolmadan bir miktar önce refresh_token ile yeni bir access_token alın. Confidential client'larda yenileme isteği de client_secret ile gönderilir (public client için bkz. dipnot ¹). Token exchange'de olduğu gibi client_secret'ı form alanı veya HTTP Basic ile gönderebilirsiniz.

curl — refresh token
curl -X POST https://id.parasut.com/realms/parasut/protocol/openid-connect/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=refresh_token" \
  -d "client_id=CLIENT_ID" \
  -d "client_secret=CLIENT_SECRET" \
  -d "refresh_token=REFRESH_TOKEN"
Yanıt, token exchange ile aynı formattadır. Yanıtta genellikle yeni access_token ile birlikte yeni bir refresh_token da gelir; sonraki yenilemede dönen son refresh_token'ı kullanın.

Hızlı Referans

Endpoint'ler(Prod ortamı)
AUTHORIZATIONhttps://id.parasut.com/realms/parasut/protocol/openid-connect/auth
TOKENhttps://id.parasut.com/realms/parasut/protocol/openid-connect/token
LOGOUThttps://id.parasut.com/realms/parasut/protocol/openid-connect/logout
USERINFOhttps://id.parasut.com/realms/parasut/protocol/openid-connect/userinfo

OIDC DISCOVERY

Tüm endpoint URL'leri, desteklenen scope'lar ve imzalama anahtarları için well-known adresini kullanabilirsiniz:

https://id.parasut.com/realms/parasut/.well-known/openid-configuration
API Başvurusu YapAPI Dokümantasyonu