2 · Token Exchange (/plugin-api/oauth/token)

İstek

POST https://<runtime>/plugin-api/oauth/token
Content-Type: application/json

{
  "grant_type": "authorization_code",
  "code": "<connect ile gelen tek-kullanımlık code>",
  "client_id": "<pluginId>",
  "client_secret": "<portalda üretilen cs_...>"
}

Yanıt

200 OK
{
  "tokenType": "...",       // token tipi
  "tenantId": "...",        // tenant kimliği (kurulumu bununla eşle)
  "pluginId": "...",        // eklenti (client) id
  "version": "...",         // kurulum manifest sürümü
  "scopes": ["orders:read", "events:subscribe", "..."],  // gerçekten verilen yetkiler
  "apiKey": "...",          // bu tenant için Callback API çağrılarında kullan
  "webhookSecret": "..."    // bu tenant'ın webhook + session token imzası
}

• apiKey — bu tenant için Callback API çağrılarında kullanılır. Üç parçalıdır: serverId.pluginId.secret. Buradaki serverId, zarftaki (envelope) tenantId ile aynı kimliktir (tenantId = serverId'nin dış adı).
• webhookSecret — webhook + hook imza doğrulaması ve session token doğrulaması.
• tenantId — tenant kimliği; kurulumu ve gelen event'leri bununla eşle. (apiKey'in içindeki serverId'nin dış adı — aynı kimlik.)
• scopes — kurulumda fiilen verilen yetkiler (manifest'te istediğinin alt kümesi olabilir).

Adımlar

1. /connect'te aldığın code + client_id + client_secret ile POST et.
2. Kalıcı dört değeri (tenantId, apiKey, webhookSecret, scopes) tenantId başına güvenli sakla.
3. scopes'a göre özelliklerini koşullu çalıştır (verilmeyen yetkiyi varsayma).

apiKey rotasyonu (sızıntı / periyodik)

• Kurulumun apiKey'ini portaldan yenileyebilirsin: eklentinin Teslim logları → Teslim Sağlığı tablosunda kurulum satırındaki "API key yenile" butonu.
• Eski key anında geçersiz olur — yeni key yalnız bir kez gösterilir; entegrasyonun yeni key'i alana kadar API çağrıların 401 alır. Kurulumu kaldırıp yeniden kurmana gerek yok.
• Kullanım: sızıntı şüphesi veya periyodik rotasyon. Henüz bağlanmamış (exchange tamamlanmamış) kurulumda apiKey olmadığından rotate çalışmaz.
• apiKey'in başka bir son kullanma süresi yoktur — rotate edilene (veya kurulum kaldırılana) kadar geçerlidir.

Hata yanıtı (RFC 6749)

Token ucu artık standart OAuth 2.0 hatası döndürür — başarı yanıtı değişmedi (Connect akışını bozmaz), yalnız hata şekli standartlaştı:

• Gövde: { error, error_description } (standart OAuth lib'leri bunu bekler).
• Geri uyum için { success:false, message } alanları da gönderilir (kademeli geçiş) — ama HTTP status'a göre dallan.