# Kimlik Doğrulama

Her API isteği, <span data-t="appName">Your AI Connector</span>'ı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ı](#the-paid-feature-gate) bölümüne bakın. Bir anahtar oluşturmak için [API Erişimi](../integrations/api-access.md) 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**

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

**JavaScript**

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

**Python**

```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**

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

**JavaScript**

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

**Python**

```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**

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

**JavaScript**

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

**Python**

```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 <span data-t="appName">Your AI Connector</span>'ı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 <span data-t="appName">Your AI Connector</span> 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ı](api-keys.md) 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:

```json
{
  "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 [<span data-t="supportEmail">hi@youraiconnector.com</span>](mailto:hi@youraiconnector.com). A missing or wrong key returns `401` instead:

```json
{
  "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ı](#key-scopes).
- **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ı](api-keys.md).
- **Her zaman HTTPS kullanın,** böylece anahtar aktarım sırasında şifrelenmiş olur.

---

## Sonraki adımlar

- [Başlarken](getting-started.md) — ilk isteğiniz ve kaynak kılavuzları.
- [Hatalar ve Sayfalama](errors-and-pagination.md) — hataları yönetin ve sonuçlar arasında gezinin.
- [API Anahtarları](api-keys.md) — anahtarınızı yenileyin, iptal edin ve kullanımını kontrol edin.