API Anahtarları API’si #

Bu uç noktalar, hesabınızın API anahtarlarını kod üzerinden yönetmenizi sağlar. Hepsi yalnızca çağrıyı yapan hesabın kendi anahtarları üzerinde işlem yapar.

İki tür anahtar vardır ve bunlar ayrı yollarda bulunur:

• Ana anahtarınız — Ayarlar → Entegrasyonlar → API Anahtarı altındaki tek tam erişimli anahtar. Maskelenmiş önizlemesine bakın, hız sınırı kullanımınızı kontrol edin, anahtarı döndürün veya iptal edin. Bunlar aşağıdaki /api-keys/current, /api-keys/rotate ve /api-keys/usage uç noktalarıdır.
• Kapsamlı anahtarlar — Belirli bir iş için oluşturduğunuz, her biri API’nin seçtiğiniz bölümleriyle sınırlı olan ekstra, adlandırılmış anahtarlar. Bunlar, Kapsamlı anahtarlar altındaki /api-keys ve /api-keys/{id} uç noktalarıdır. Bir tane oluşturduğunuzda ana anahtarınızla ilgili hiçbir şey değişmez; mevcut entegrasyonlar etkilenmeden çalışmaya devam eder.

Aşağıdaki tüm yollar, API temel URL’sine göre belirlenmiştir:

https://api.youraiconnector.com/v1

Her isteğin kimliği doğrulanmalıdır. Kabul edilen dört yöntem için Kimlik Doğrulama bölümüne bakın. Buradaki örnekler X-API-Key başlığını (ve cURL için bir sorgu parametresi biçimini) kullanır.

Bunu önce okuyun. Anahtarınızı döndürmek veya iptal etmek anında etkili olur. Her iki çağrı da başarılı olduğu anda eski anahtar çalışmayı durdurur; onu kullanan her entegrasyon 401 hataları almaya başlar. Buna göre plan yapın: bir bakım penceresi sırasında döndürme işlemini gerçekleştirin ve tüm entegrasyonlarınızı hemen güncelleyin.

Mevcut anahtar meta verilerini al #

Etkin anahtarınızı döndürür: alınabilir bir kopya mevcut olduğunda api_key içindeki tam anahtarı, maskelenmiş bir önizlemeyi (ilk 4 ve son 4 karakter) ve mevcut olduğunda oluşturulma tarihini gösterir. api_key, alınabilir kopyaların tutulmadığı tarihlerden önce oluşturulan anahtarlar için null değerindedir — bir kez döndürün, yeni anahtar daha sonra tekrar görüntülenebilir.

GET /api-keys/current

cURL

curl "https://api.youraiconnector.com/v1/api-keys/current?apiKey=YOUR_API_KEY"

JavaScript

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

Python

import requests

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

Yanıt

{
  "success": true,
  "api_key": "abcdEFGH1234ijkl5678MNOP9012qrst",
  "api_key_masked": "abcd...qrst",
  "created_at": "2026-06-01T10:00:00.000Z"
}

Hesabın API anahtarı yoksa, yanıt { "success": false, "error": "No API key found for this account" } ile birlikte 404 olur.

Hız sınırı kullanımını al #

Mevcut pencere için hız sınırı kullanımınızı döndürür: pencere başına istek sınırı, şu ana kadar kaç isteğin sayıldığı, kaç tane kaldığı ve pencerenin ne zaman sıfırlanacağı. Bunu, entegrasyonunuzun 429 yanıtlarına ulaşmadan önce yavaşlamasını sağlamak için istemci tarafında hız sınırlaması oluşturmak amacıyla kullanın.

GET /api-keys/usage

cURL

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

JavaScript

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

Python

import requests

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

Yanıt

{
  "success": true,
  "usage": {
    "limit": 300,
    "window_seconds": 60,
    "used": 37,
    "remaining": 263,
    "window_resets_at": "2026-06-09T12:01:00.000Z"
  }
}

Mevcut pencerede henüz hiçbir istek kaydedilmediyse, kullanım sıfır olarak bildirilir ve yanıt bunun nedenini açıklayan bir note alanı içerir.

Anahtarı döndür #

Yeni bir API anahtarı oluşturur ve aynı adımda öncekini geçersiz kılar. Bunu, anahtarınızın sızdığından şüpheleniyorsanız veya düzenli bir kimlik bilgisi döndürme politikasının bir parçası olarak kullanın.

POST /api-keys/rotate

Yeni anahtar yalnızca bir kez gösterilir. Bu yanıt içerisinde döndürülür ve sonrasında tamamı tekrar alınamaz; bu nedenle aldığınız anda güvenli bir şekilde saklayın. Önceki anahtar, bu çağrı başarılı olduğu anda çalışmayı durdurur, bu yüzden onu kullanan tüm entegrasyonları güncelleyin.

cURL

curl -X POST "https://api.youraiconnector.com/v1/api-keys/rotate?apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/api-keys/rotate", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();
// Save data.api_key now — it will not be shown again.

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/api-keys/rotate",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
# Save data["api_key"] now — it will not be shown again.

Yanıt

{
  "success": true,
  "api_key": "abcdEFGH1234ijkl5678MNOP9012qrst",
  "message": "API key rotated. The previous key is no longer valid. Store this key now — it will not be shown again."
}

Anahtarı iptal et #

Hesabınızın API anahtarını kalıcı olarak siler. İptal işlemi anında gerçekleşir: Make, Zapier veya özel betikler gibi entegrasyonlar dahil olmak üzere, iptal edilen anahtarı kullanan sonraki tüm istekler 401 ile reddedilir. Daha sonra API erişimini geri yüklemek için, uygulamaya giriş yapmış durumdayken hesap ayarlarınızdan yeni bir anahtar oluşturun.

DELETE /api-keys/current

Geri alma işlemi yoktur. Döndürme işleminin aksine, iptal işlemi size yeni bir anahtar vermez. Yalnızca API erişimini durdurmak istediğinizde iptal edin (örneğin, hemen değiştiremeyeceğiniz sızdırılmış bir anahtar durumunda).

cURL

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

JavaScript

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

Python

import requests

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

Yanıt

{
  "success": true,
  "revoked": true,
  "message": "API key revoked. All requests using it will be rejected immediately."
}

Hesapta iptal edilecek bir anahtar yoksa, yanıt 404 olur.

Kapsamlı anahtarlar #

Kapsamlı anahtar, yalnızca o işin ihtiyaç duyduğu erişimi taşıyan, belirli bir iş için oluşturduğunuz ekstra bir API anahtarıdır. Klasik durum: Bir müşteri panosunu, raporlama aracını veya dahili bir betiği, mesaj gönderebilecek, yapay zeka temsilcilerinizi değiştirebilecek veya telefon numarası satın alabilecek bir anahtarı teslim etmeden hesabınıza yönlendirmek istersiniz.

Kısıtlama anahtarın kendisiyle birlikte hareket eder, bu nedenle anahtara sahip olan kişi yalnızca oluşturduğunuzda izin verdiğiniz işlemleri yapabilir.

Neleri kısıtlayabilirsiniz

Ayrıca bir anahtara bir expires_at tarihi verebilirsiniz (ISO 8601 formatında ve gelecekteki bir tarih olmalıdır). O andan sonra anahtar kendi kendine çalışmayı durdurur. Bu alanı boş bırakırsanız, siz iptal edene kadar anahtarın süresi asla dolmaz.

Reddetmeler kapalı başarısız olur. Bir istek, anahtarın izin verdiği kapsamın dışına çıkarsa, işleme alınmak yerine reddedilir: salt okunur bir anahtarla yapılan yazma işlemi error_code: "key_read_only" ile 403 döndürür ve anahtarın izin verilen bölümlerinin dışındaki herhangi bir şey error_code: "key_scope_denied" ile 403 döndürür. Kapsamlı bir anahtar beklenmedik bir 403 alırsa, çağırdığınız uç nokta basitçe kapsamları içinde değildir; anahtarın kapsamını genişletin veya ana anahtarınızı kullanın.

Anahtarları yalnızca hesap sahibi yönetir. Bu dört uç nokta, ana anahtarınızı veya uygulamadaki bir sahip oturumunu gerektirir. Kapsamlı bir anahtar, kendisi de dahil olmak üzere hiçbir anahtarı listeleyemez, oluşturamaz, düzenleyemez veya iptal edemez; bu nedenle kısıtlanmış bir anahtar asla daha geniş yetkili bir anahtar oluşturmak için kullanılamaz. Bunu denemek error_code: "key_scope_denied" ile 403 döndürür. Aynı nedenle, API Keys verebileceğiniz bir bölüm değildir: bunu istemek error_code: "invalid_scopes" ile 400 döndürür.

Kapsamlı anahtarları listele #

Hesabın kapsamlı anahtarlarını, en yenisi ilk sırada olacak şekilde (200’e kadar) döndürür; nelerin ne zaman geri çekildiğini görebilmeniz için iptal edilenler de dahildir. Yalnızca maskelenmiş önizlemeler geri döner; kapsamlı bir anahtarın değeri yalnızca oluşturulma anında gösterilir ve sonrasında asla geri alınamaz.

GET /api-keys

cURL

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

Yanıt

{
  "success": true,
  "api_keys": [
    {
      "id": "key_9f2c1a7b4d6e8f0a1b2c3d4e5f60718a",
      "label": "Client dashboard - Acme",
      "key_preview": "abcd...qrst",
      "scopes": {
        "read_only": true,
        "tags": ["Analytics"],
        "sub_account_ids": [],
        "rate_limit_per_min": 60
      },
      "expires_at": null,
      "last_used_at": "2026-08-20T14:03:00.000Z",
      "created_at": "2026-08-14T09:12:00.000Z",
      "revoked_at": null,
      "revoked": false
    }
  ]
}

Kapsamlı anahtar oluştur #

Yeni bir kapsamlı anahtar oluşturur ve değerini bir kez döndürür.

POST /api-keys

Anahtar yalnızca bir kez gösterilir. Bu yanıtın içindedir ve başka hiçbir yerde, hiçbir zaman görünmez; daha sonra tekrar görüntülemenin bir yolu yoktur. Aldığınız anda kaydedin. Kaybederseniz, iptal edin ve başka bir tane oluşturun.

Gövde alanları — hepsi isteğe bağlıdır:

cURL

curl -X POST "https://api.youraiconnector.com/v1/api-keys" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Client dashboard - Acme",
    "scopes": {
      "read_only": true,
      "tags": ["Analytics"],
      "sub_account_ids": [],
      "rate_limit_per_min": 60
    }
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/api-keys", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    label: "Client dashboard - Acme",
    scopes: { read_only: true, tags: ["Analytics"] },
  }),
});
const data = await res.json();
// Save data.api_key now — it will not be shown again.

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/api-keys",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "label": "Client dashboard - Acme",
        "scopes": {"read_only": True, "tags": ["Analytics"]},
    },
)
data = res.json()
# Save data["api_key"] now — it will not be shown again.

Yanıt — 201 Created

{
  "success": true,
  "api_key": "abcdEFGH1234ijkl5678MNOP9012qrst",
  "key": {
    "id": "key_9f2c1a7b4d6e8f0a1b2c3d4e5f60718a",
    "label": "Client dashboard - Acme",
    "key_preview": "abcd...qrst",
    "scopes": {
      "read_only": true,
      "tags": ["Analytics"],
      "sub_account_ids": [],
      "rate_limit_per_min": 60
    },
    "expires_at": null,
    "revoked": false
  },
  "message": "Store this key now — it is shown once and cannot be retrieved again."
}

Buna göre geliştirme yaparken bilmeniz gereken birkaç detay:

• scopes alanını atlamak, boş bir tags listesi göndermekle aynı şey değildir. scopes alanını tamamen boş bırakırsanız güvenli varsayılan değerleri (salt okunur, yalnızca Analytics) alırsınız. "tags": [] alanını kasten gönderirseniz anahtar her bölümü kullanabilir; bu, kısıtlanmamış bir anahtar için kasıtlı bir istek olarak okunur.
• read_only, siz açıkça false göndermediğiniz sürece true kalır. Bir yazım hatası veya eksik bayrak, yanlışlıkla yazma yetkisi olan bir anahtar oluşturamaz.

Kapsamlı bir anahtarı güncelleme #

Bir anahtarın etiketini, kapsamlarını ve/veya son kullanma tarihini değiştirir. Üçünden herhangi bir kombinasyonu gönderin; hiçbirini göndermemek 400 döndürür.

PATCH /api-keys/{id}

{id}, listedeki anahtarın id değeridir (yani key_... değeri), anahtarın kendisi değildir.

Kapsamlar birleştirilmez, değiştirilir. Gönderdiğiniz her şey anahtarın tam izin kümesi haline gelir. Bu kasıtlıdır: bir anahtarı daraltmak, eski ve daha geniş erişimin sessizce yerinde kalmasına asla neden olamaz. Sadece değiştirdiğiniz alanı değil, her zaman istediğiniz tam scopes nesnesini gönderin.

Anahtarın değeri asla değişmez. Kapsamlı bir anahtar için yerinde döndürme (rotate) yoktur; bir anahtarı yenilemek için yeni bir anahtar oluşturun ve eskisini iptal edin, böylece bir kimlik bilgisinin erişimi, onu tutan bir entegrasyon altında asla değişemez.

cURL

curl -X PATCH "https://api.youraiconnector.com/v1/api-keys/key_9f2c1a7b4d6e8f0a1b2c3d4e5f60718a" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Client dashboard - Acme (read-only)",
    "scopes": {
      "read_only": true,
      "tags": ["Analytics", "Campaigns"],
      "sub_account_ids": [],
      "rate_limit_per_min": 30
    }
  }'

Yanıt

{
  "success": true,
  "key": {
    "id": "key_9f2c1a7b4d6e8f0a1b2c3d4e5f60718a",
    "label": "Client dashboard - Acme (read-only)",
    "key_preview": "abcd...qrst",
    "scopes": {
      "read_only": true,
      "tags": ["Analytics", "Campaigns"],
      "sub_account_ids": [],
      "rate_limit_per_min": 30
    },
    "expires_at": null,
    "last_used_at": "2026-08-20T14:03:00.000Z",
    "created_at": "2026-08-14T09:12:00.000Z",
    "revoked_at": null,
    "revoked": false
  }
}

Hesabınızda bu kimliğe sahip bir anahtar yoksa, yanıt 404 olur.

Kapsamlı bir anahtarı iptal etme #

İptal işlemi anında gerçekleşir: bu anahtarı kullanan bir sonraki istek 401 ile reddedilir. Ana anahtarınız ve diğer tüm kapsamlı anahtarlarınız bu durumdan etkilenmez.

DELETE /api-keys/{id}

Anahtar, listenizde "revoked": true olarak işaretlenmiş şekilde kalır; böylece nelerin var olduğu ve nelere erişebildiği kaydını tutmaya devam edersiniz. Zaten iptal edilmiş bir anahtarı iptal etme işlemi başarılı olur ancak hiçbir şeyi değiştirmez.

cURL

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

Yanıt

{
  "success": true,
  "revoked": true,
  "id": "key_9f2c1a7b4d6e8f0a1b2c3d4e5f60718a",
  "message": "API key revoked. All requests using it will be rejected immediately."
}

API Anahtarı API hataları #

API anahtarı uç noktaları standart hata zarfını döndürür:

{
  "success": false,
  "error": "No API key found for this account"
}

Bir API anahtarı uç noktasında, eksik veya geçersiz bir anahtar 401 döndürür ve dosyada anahtarı olmayan bir hesap 404 döndürür. Her uç noktanın döndürebileceği paylaşılan kodlar — 400, 403 (planınız API erişimini içermiyor), 429 (hız sınırı) ve 500 — yeniden deneme rehberliği ile birlikte Hatalar ve Sayfalandırma bölümünde listelenmiştir.

Kapsamlı anahtar uç noktaları, durumları birbirinden ayırt edebilmeniz için error_code alanına birkaç adlandırılmış kod ekler:

Sonraki adımlar #

• Kimlik Doğrulama — bir isteğin kimliğini doğrulamanın dört yolu ve anahtar kapsamlarının nasıl uygulandığı.
• Hatalar ve Hız Sınırları — durum kodları ve 300 istek/dakika sınırı.