Kimlik doğrulama

/api/integrations/v1 altındaki her rota Authorization başlığında bir bearer kimlik bilgisi alır: anahtarın kendisi ya da onun için verilmiş bir erişim belirteci. İkisi de her çağrıda aynı kontrollerden geçer: anahtar iptal edilmemiş ve süresi dolmamış, çağrı izin verilen bir adresten geliyor, anahtar rotanın kapsamına sahip ve şirketinizde Entegrasyon API’si hâlâ açık.

Anahtarlar yalnız /api/integrations/v1 altında çalışır. Platformun geri kalanı onları reddeder.

Doğrudan anahtar

Anahtarı her çağrıda gönderin. Sabit bir başlık gönderebilen her araç (BPM aracı, ETL işi, betik) için en kısa yoldur.

curl "https://app.quatlasglobal.com/api/integrations/v1/shipment-requests/<talep-kimliği>" \
  -H "Authorization: Bearer $QUATLAS_KEY"

OAuth 2.0 client credentials

Güvenlik politikanız her çağrıda sabit bir anahtar dolaşmasına izin vermiyorsa, anahtarı belirteç adresinde kısa ömürlü bir erişim belirteciyle değiştirin (RFC 6749, bölüm 4.4) ve çağrılarda belirteci gönderin.

Belirteç adresi	POST https://app.quatlasglobal.com/api/integrations/v1/oauth/token
Gövde	application/x-www-form-urlencoded, grant_type=client_credentials
İstemci kimliği	Anahtarın öneki (qk_ ya da qk_test_ ve sonraki 12 karakter)
İstemci sırrı	Anahtarın kendisi
Belirteç ömrü	900 saniye (15 dakika)

İstemci kimliğini ya HTTP Basic ile (client_secret_basic) ya da client_id ve client_secret form alanlarıyla (client_secret_post) gösterir; bir istekte ikisi birden değil.

HTTP Basic

curl "https://app.quatlasglobal.com/api/integrations/v1/oauth/token" \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -d grant_type=client_credentials

Form alanları

curl "https://app.quatlasglobal.com/api/integrations/v1/oauth/token" \
  -d grant_type=client_credentials \
  --data-urlencode "client_id=$CLIENT_ID" \
  --data-urlencode "client_secret=$CLIENT_SECRET"

{
  "access_token": "eyJ...",
  "token_type": "Bearer",
  "expires_in": 900,
  "scope": "requests:read requests:write"
}

Ardından API’yi Authorization: Bearer <access_token> ile çağırın. expires_in dolmadan yeni bir belirteç alın; yanıt hiçbir zaman önbelleğe alınmaz (Cache-Control: no-store).

• Kapsamlar. Anahtarın sahip olduğundan daha az kapsam istemek için isteğe bağlı scope alanını (boşlukla ayrılmış) gönderin. Gönderilmezse belirteç anahtarın tüm kapsamlarını alır. Anahtarda olmayan bir kapsam istemek invalid_scope döner.
• İptal. Belirteç yalnız anahtarı geçerli olduğu sürece geçerlidir: anahtar her çağrıda yeniden kontrol edilir, iptal edilen anahtarın belirteçleri hemen reddedilir.
• Sınır. Belirteç adresi IP adresi başına dakikada 20 isteğe izin verir.
• Hatalar RFC 6749, bölüm 5.2 biçimindedir:

Durum	error	Ne zaman
400	invalid_request	Form-encoded değil, bir alan iki kez gönderilmiş, hem Basic hem form kimlik bilgisi var ya da client_id Basic kullanıcısından farklı.
400	unsupported_grant_type	grant_type, client_credentials değil.
400	invalid_scope	İstenen bir kapsam anahtara verilmemiş.
401	invalid_client	İstemcinin kimliği doğrulanamadı. Neden hiçbir zaman söylenmez.

Yalnız OAuth

Bir anahtar, entegrasyonu oluşturulurken Yalnız OAuth olarak ayarlanabilir. O zaman anahtarın kendisi belirteç adresi dışındaki her rotada reddedilir; anahtar sıradan çağrılarda dolaşmaz ve her çağrı 15 dakikada ölen bir belirteç taşır.

Retler

Durum	code	Anlamı
401	Integration.Unauthorized	Geçerli bir anahtar ya da belirteç yok: yanlış, iptal edilmiş, süresi dolmuş, IP izin listesi dışından, doğrudan gönderilmiş bir Yalnız OAuth anahtarı ya da süresi dolmuş bir belirteç. Her neden için yanıt aynıdır; Sahip ya da Yöneticiniz çağrıyı çağrı kaydında görür.
403	Integration.Forbidden	Anahtar geçerli ama rotanın kapsamı yok.
403	Integration.AccessDenied	Anahtar şu an kullanılamıyor. Sahip ya da Yöneticinize sorun.
403	Company.Suspended	Şirket hesabınız durdurulmuş.

Yenileme

Anahtarı süresi dolmadan ya da açığa çıkmış olabileceği her durumda yenileyin. Sahip ya da bir Yönetici Ayarlar > Entegrasyonlar altında anahtarda Yenile’yi seçer (iki adımlı doğrulamayla):

• Aynı entegrasyon için aynı kapsam, IP izin listesi ve OAuth ayarıyla yeni bir anahtar çıkarılır ve bir kez gösterilir.
• Eski anahtar 7 gün daha çalışır; yenisini sistemlerinize kesintisiz koyabilirsiniz. Eski anahtarı iptal etmek bu süreyi hemen bitirir.
• Bir entegrasyonun aynı anda en fazla 2 etkin anahtarı olur.

Bitiş

Her anahtarın süresi dolar; en geç çıkarıldıktan 12 ay sonra (varsayılan 12 ay). Şirketinizin Sahip ve Yöneticileri bitişten 30 gün, 7 gün ve 1 gün önce uygulamada ve e-postayla uyarılır. Bitişten sonra anahtar 401 alır. Ondan önce yenileyin.

IP izin listesi

Bir anahtar, çağrılarınızın geldiği adreslerle sınırlanabilir: en fazla 20 giriş; her biri bir IPv4 ya da IPv6 adresi veya 203.0.113.0/24 gibi bir CIDR bloğu. Boş liste her kaynağa izin verir. Başka bir adresten gelen çağrı 401 alır. Sistemlerinizin sabit çıkış adresleri varsa listeyi doldurmanızı öneririz.

Not

Belirteç adresi de izin listesine bakar: anahtarın izin vermediği bir adresten belirteç alınamaz.

Anahtarları güvende tutmak

• Anahtarları gizli anahtar kasasında tutun; kodda, e-postada ya da sohbette değil.
• Her entegrasyona yalnız ihtiyaç duyduğu kapsamları verin; her sistem için ayrı bir entegrasyon kullanın.
• Üretim dışındaki her yerde test anahtarı kullanın.
• Sızmış olabilecek bir anahtarı hemen iptal edin: iptal, belirteçleriyle birlikte anında geçerlidir.