Your AI Connector Docs

Kimlik Doğrulama

Her API isteği, Your AI Connector'ın siz olduğunuzu ve hangi hesap üzerinde işlem yapacağını bilmesi için API anahtarınızı taşımalıdır. Anahtarı dört farklı şekilde gönderebilirsiniz; bunların hepsi API anahtarı kimlik doğrulamasını kabul eden her uç noktada çalışır, bu nedenle kurulumunuza en uygun olanı seçin.

API erişimi ücretli bir özelliktir. Planınız bunu içermiyorsa, anahtarın kendisi geçerli olsa bile istekler 403 ile reddedilir — aşağıda yer alan Ücretli özellik sınırı bölümüne bakın. Bir anahtar oluşturmak için API Erişimi bölümüne bakın.

Sadece HTTPS. Tüm istekler güvenli bir bağlantı kullanmalıdır. Düz HTTP istekleri, kimlik doğrulama çalışmadan önce reddedilir.

Dört yönteme genel bakış

Yöntem Taşıyıcı Ne zaman kullanılır
Sorgu parametresi ?apiKey=YOUR_API_KEY Hızlı testler ve tarayıcı URL’leri
Başlık X-API-Key: YOUR_API_KEY Üretim entegrasyonları
Bearer başlığı Authorization: Bearer YOUR_API_KEY Üretim entegrasyonları
Firebase ID belirteci Authorization: Bearer <ID token> Sadece birinci taraf uygulama oturumları

Birden fazlası mevcut olduğunda, sorgu parametresi önceliklidir, ardından X-API-Key başlığı ve son olarak bearer belirteci gelir. Uygulamada genellikle sadece birini gönderirsiniz.

1. Sorgu parametresi — ?apiKey=

Anahtarınızı web adresinin sonuna ekleyin. Bu en basit biçimdir ve her zaman çalışır, bu da onu hızlı testler, betikler ve eski araçlar için ideal kılar.

cURL

curl "https://api.youraiconnector.com/v1/contacts?apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/contacts?apiKey=YOUR_API_KEY");
const data = await res.json();

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/contacts",
    params={"apiKey": "YOUR_API_KEY"},
)
data = res.json()

Dikkat: Web adresleri tarayıcı geçmişinde, sunucu erişim günlüklerinde ve proxy günlüklerinde görünür. Hızlı bir testin ötesindeki her şey için, anahtarınızın düz metin olarak diske yazılmaması adına aşağıdaki başlık yöntemlerinden birini tercih edin.

2. X-API-Key başlığı

Anahtarı özel bir başlıkta gönderin. Bu, anahtarı URL’den uzak tutar ve üretim ortamları için önerilen seçimdir.

cURL

curl "https://api.youraiconnector.com/v1/contacts" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/contacts", {
  headers: {
    "X-API-Key": "YOUR_API_KEY",
  },
});
const data = await res.json();

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/contacts",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

3. Authorization: Bearer başlığı

Anahtarı standart bir bearer token olarak da iletebilirsiniz. Bu, HTTP istemciniz veya çerçeveniz Authorization başlıkları için yerleşik desteğe sahip olduğunda kullanışlıdır.

cURL

curl "https://api.youraiconnector.com/v1/contacts" \
  -H "Authorization: Bearer YOUR_API_KEY"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/contacts", {
  headers: {
    Authorization: "Bearer YOUR_API_KEY",
  },
});
const data = await res.json();

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/contacts",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
)
data = res.json()

API, API anahtarınızı giriş token’ından otomatik olarak ayırt eder, bu nedenle bu yöntem tıpkı X-API-Key gibi çalışır.

4. Firebase ID token (yalnızca birinci taraf)

Kullanıcıların Your AI Connector'ın kendi girişi üzerinden oturum açtığı bir birinci taraf uygulaması geliştiriyorsanız, API anahtarı yerine oturum açmış kullanıcının Firebase ID token’ını bearer token olarak iletebilirsiniz:

Authorization: Bearer <Firebase ID token>

Token her istekte doğrulanır ve oturum açmış hesapla eşleştirilir. Bu yöntem yalnızca birinci taraf uygulama oturumları içindir — bu token’ları harici bir entegrasyondan oluşturamazsınız ve normal uygulama girişi sürecinden geçmeden bir tane elde etmenin yolu yoktur. Sunucudan sunucuya ve üçüncü taraf entegrasyonları için bir API anahtarı (yöntem 1–3) kullanın.

Hangisinin ne zaman kullanılacağı

  • Hızlı testler ve tek seferlik betikler → sorgu parametresi (?apiKey=). Yazması en hızlı olanıdır, tarayıcıda çalışır.
  • Üretim entegrasyonları ve sunucudan sunucuya çağrılar → X-API-Key veya Authorization: Bearer YOUR_API_KEY. Anahtarı URL’lerden ve günlüklerden uzak tutar.
  • Oturum açmış bir Your AI Connector kullanıcısına sahip birinci taraf uygulamalar → Authorization: Bearer <Firebase ID token>.

Anahtar kapsamları

Hesabınızın bir ana API anahtarı vardır; bu anahtar Ayarlar → Entegrasyonlar → API Anahtarı altında bulunur. Hesabın yapabileceği her şeye tam erişim sağlar.

Ayrıca ek kapsamlı anahtarlar da oluşturabilirsiniz: yalnızca seçtiğiniz API bölümlerine erişebilen adlandırılmış anahtarlar; örneğin, bir raporlama panosu için Analiz ile sınırlandırılmış salt okunur bir anahtar. Kapsamlı bir anahtar, tıpkı ana anahtar gibi (yukarıdaki 1-3 yöntemlerinden herhangi biriyle) gönderilir, ancak her istekte kendi izinlerine göre kontrol edilir:

  • İzin verilen alanlarının dışındaki istekler reddedilir. Salt okunur bir anahtarla yazma işlemi veya anahtara verilmeyen bir bölüme yapılan çağrı, error_code alanında key_read_only veya key_scope_denied ile birlikte 403 olarak döner. Kontrol kasıtlı olarak katıdır: anahtarın izin verilen alanlarının açıkça içinde olmayan her şey, izin verilmek yerine reddedilir; bu nedenle bu 403 hatalarından birini görürseniz, anahtarın ilgili uç noktayı kapsamadığı anlamına gelir.
  • Kendi hız sınırı bütçesine sahiptir. Kapsamlı bir anahtar, ana anahtarınızdan ayrı olarak sayılır; bu sayede kapsamlı bir anahtar kullanan yoğun bir pano, diğer entegrasyonlarınızın bağlı olduğu kotayı tüketemez. Anahtarı oluştururken bu dakika başı bütçeyi siz belirlersiniz.
  • API anahtarlarını yönetemez. Yalnızca hesap sahibi (oturum açmış şekilde veya ana anahtarı kullanarak) anahtarları listeleyebilir, oluşturabilir, düzenleyebilir, yenileyebilir veya iptal edebilir. Kapsamlı bir anahtar asla kendisinden daha geniş yetkili bir anahtar oluşturamaz.

Kapsamlı anahtarların nasıl oluşturulacağı, düzenleneceği ve iptal edileceği hakkında bilgi için API Anahtarları bölümüne bakın.

Ücretli özellik sınırı

API erişimi ücretli bir özelliktir. Planınız bunu içermediğinde, aksi takdirde geçerli olan bir anahtarla yapılan istek 403 ile reddedilir:

{
  "success": false,
  "error_code": 403,
  "error": "This action requires the \"api_access\" feature, which is not enabled for this account."
}

If you see this, check your plan or contact hi@youraiconnector.com. A missing or wrong key returns 401 instead:

{
  "success": false,
  "error_code": 401,
  "error": "Invalid API key"
}

Anahtarınızı güvende tutma

  • Anahtarı bir parola gibi saklayın. Ana anahtarınız hesabınıza tam erişim sağlar. Bir araca veya sadece kısmi erişime ihtiyaç duyan bir kişiye anahtar vermeniz gerekiyorsa, bunun yerine kapsamlı bir anahtar oluşturun; bkz. Anahtar kapsamları.
  • Sunucu tarafında tutun. Asla tarayıcı JavaScript’ine, mobil uygulama paketine veya son kullanıcının okuyabileceği herhangi bir koda gömmeyin.
  • Kaynak kod kontrolünde değil, bir gizli yönetici (secret manager) veya sunucu tarafı yapılandırmasında saklayın.
  • Sızdırılırsa yenileyin. Panodan yeni bir anahtar oluşturun veya POST https://api.youraiconnector.com/v1/api-keys/rotate çağrısı yapın; bu, eski anahtarı anında geçersiz kılar. Bkz. API Anahtarları.
  • Her zaman HTTPS kullanın, böylece anahtar aktarım sırasında şifrelenmiş olur.

Sonraki adımlar