Kimlik bilgileri ve token'lar

Token endpoint’i

POST https://{store domain}/apps/token — özel bir uygulamanın kullandığı OAuth 2.0 client credentials grant’i: tek bir mağazaya kuruludur ve kendi kimlik bilgilerini sunar; dolayısıyla yönlendirilecek bir kullanıcı yoktur. Aynı endpoint, bir tüccarın onayıyla kurulan uygulama için authorization_code (PKCE ile) ve refresh_token grant’lerine de hizmet eder; aşağıdaki tablo ve örnekler client credentials grant’idir.

Form alanı	Değer
grant_type	tam olarak client_credentials
client_id	ciqra_ci_… id’niz
client_secret	ciqra_cs_… secret’ınız

Gövde application/x-www-form-urlencoded olmalıdır. İstemci kimlik bilgilerini ya client_id / client_secret form alanları ya da bir HTTP Basic header’ı ile gönderin (Authorization: Basic base64(client_id:client_secret), RFC 6749 §2.3.1) — çoğu OAuth kütüphanesi varsayılan olarak böyle yapar. İkisini birden göndermek 400 invalid_request ile reddedilir. Yanıt Cache-Control: no-store taşır.

Başarılı — 200

{
  "access_token": "ciqra_at_…",
  "token_type": "Bearer",
  "expires_in": 3600,
  "accessToken": "ciqra_at_…",
  "tokenType": "Bearer",
  "expiresIn": 3600,
  "scope": "read_products write_products",
  "scopeNotYetEnforced": ""
}

Alan	Anlamı
access_token	Authorization: Bearer <access_token> olarak gönderin.
token_type	Her zaman Bearer.
expires_in	Süresinin dolmasına kalan saniye — varsayılan olarak bir saat.
accessToken, tokenType, expiresIn	Aynı üç değerin camelCase hâli; mevcut uygulamalar çalışmaya devam etsin diye korunur. Yeni kodda snake_case alanları kullanın (RFC 6749 §5.1); standart OAuth istemci kütüphaneleri bunları ek bir çaba olmadan okur.
scope	Boşlukla ayrılmış etkin scope’lar (yetkiler): verilenler, artı her write_ scope’unun ima ettiği read_ scope’u. Sıra önemli değildir.
scopeNotYetEnforced	scope içinden henüz hiçbir endpoint’in dikkate almadığı alt küme (yoksa boş string) — burada yalnızca ayrılmış bir scope görünebilir: bir write_ scope’unun içerdiği ya da ayrılmadan önce verilmiş olan. Bkz. scope’lar.

Refresh token yoktur. expiresIn dolmadan kısa bir süre önce yeni bir token isteyin — referans uygulama bunu bir dakika erken yapar.

Hatalar

Durum	Gövde	Neden
400	{"error":"invalid_request","error_description":"…"}	Gövde form-encoded değil ya da kimlik bilgileri hem Basic header’ında hem formda gönderilmiş.
400	{"error":"unsupported_grant_type","error_description":"…"}	grant_type, client_credentials dışında bir değer.
401	{"error":"invalid_client","error_description":"Client authentication failed."}	Bilinmeyen client id, yanlış secret, uygulama aktif değil ya da bu alan adının mağazasında aktif bir kurulum yok. Bu durumlar bilerek birbirinden ayırt edilemez.
429	—	IP adresinizden dakikada 20’den fazla token isteği. Gövdeyi ayrıştırmayın.

Token endpoint’i hataları RFC 6749 §5.2’yi izler (error artı error_description). Diğer tüm uygulama route’ları bunun yerine hata zarfını kullanır.

Token tek bir mağazaya bağlıdır

Kurulum, isteğin alan adının çözüldüğü mağaza olarak aranır. Aynı kimlik bilgileri başka bir mağazanın alan adında kullanıldığında, uygulama oraya da kurulu olsa bile 401 alır — her mağazanın kurulumuna o mağazanın alan adı üzerinden erişilmelidir.

Kalıcı token’lar

Tüccar, yönetim panelinden (Ayarlar → Uygulamalar → uygulama → Token’lar) bir kurulum için uzun ömürlü bir token verebilir: bir etiket ve 30, 90, 180 ya da 365 günlük bir ömür. Token bir kez gösterilir, kurulumun mevcut scope’larını taşır ve tek tek iptal edilebilir. Yönetim paneli her token’ın en son ne zaman kullanıldığını gösterir (en fazla beş dakikada bir güncellenir).

Bunu yalnızca token değişimi yapamayan bir araç için kullanın. Sızan bir kalıcı token aylarca geçerlidir; sızan bir değişim token’ı ise bir saatten az.

Rotasyon ve iptal

• Client secret. İstek üzerine CIQRA tarafından döndürülür. Önceki secret bir örtüşme penceresi boyunca (varsayılan olarak 24 saat) çalışmaya devam eder; böylece yenisini kesinti olmadan dağıtabilirsiniz.
• İptal anında gerçekleşir. Token’lar her istekte kuruluma ve uygulamaya karşı kontrol edilir; hiçbir şey önbelleğe alınmaz. Uygulamayı kaldırmak, bir kalıcı token’ı iptal etmek veya uygulamayı askıya almak bir sonraki çağrıda etkili olur.
• Signing secret. Kurulumda bir kez verilir. Şu anda onu sizin döndürebileceğiniz bir route yok — bkz. kısıtlamalar. Ele geçirilirse CIQRA onu anında (örtüşme olmadan) emekliye ayırır ve yeni secret bizim tarafta gösterilmez; size verilene kadar teslimatlar doğrulanmaz. Olağan bir rotasyonda her teslimatı iki secret da imzalar — bkz. imzaları doğrulama.