# 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](#scoped-keys) 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](authentication.md) 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** ```bash curl "https://api.youraiconnector.com/v1/api-keys/current?apiKey=YOUR_API_KEY" ``` **JavaScript** ```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** ```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** ```json { "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** ```bash curl "https://api.youraiconnector.com/v1/api-keys/usage" \ -H "X-API-Key: YOUR_API_KEY" ``` **JavaScript** ```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** ```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** ```json { "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** ```bash curl -X POST "https://api.youraiconnector.com/v1/api-keys/rotate?apiKey=YOUR_API_KEY" ``` **JavaScript** ```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** ```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** ```json { "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** ```bash curl -X DELETE "https://api.youraiconnector.com/v1/api-keys/current" \ -H "X-API-Key: YOUR_API_KEY" ``` **JavaScript** ```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** ```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** ```json { "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** | Alan | Anlamı | |---|---| | `read_only` | `true` (varsayılan), yalnızca okuma isteklerine izin verildiği anlamına gelir. Herhangi bir oluşturma, güncelleme veya silme reddedilir. | | `tags` | Anahtarın kullanabileceği API bölümlerinin listesi; bu belgelerde ve [API gezgininde](reference.md) gördüğünüz bölüm adlarıyla yazılır — `Analytics`, `Campaigns`, `Contacts`, `Messages`, `Appointments` vb. Boş bir liste, tüm bölümler anlamına gelir. | | `sub_account_ids` | Anahtarın hangi yönetilen hesaplar üzerinde işlem yapabileceği. Boş olması yalnızca kendi hesabınız anlamına gelir; `["*"]`, fiilen yönettiğiniz herhangi bir hesap anlamına gelir. Sahiplik her istekte kontrol edilmeye devam eder. | | `rate_limit_per_min` | Bu anahtar için dakika başına istek sayısı; kendi bütçesi içinde sayılır, böylece diğer entegrasyonlarınızın kotasını tüketemez. Varsayılan olarak `60`'dir ve `300` değerinin üzerine ayarlanamaz. | 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** ```bash curl "https://api.youraiconnector.com/v1/api-keys" \ -H "X-API-Key: YOUR_API_KEY" ``` **Yanıt** ```json { "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: | Alan | Tür | Notlar | |---|---|---| | `label` | string | Listede ve Ayarlar'da görünen, anahtar için kendi belirlediğiniz ad. | | `scopes` | object | Yukarıdaki tablodaki dört alan. Nesnenin tamamını boş bırakırsanız güvenli varsayılan değerleri alırsınız: salt okunur, `Analytics` ile sınırlı, yalnızca kendi hesabınız, dakikada 60 istek. | | `expires_at` | ISO 8601 date | İsteğe bağlı son kullanma tarihi, gelecekteki bir tarih olmalıdır. | **cURL** ```bash 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** ```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** ```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` ```json { "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** ```bash 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** ```json { "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** ```bash curl -X DELETE "https://api.youraiconnector.com/v1/api-keys/key_9f2c1a7b4d6e8f0a1b2c3d4e5f60718a" \ -H "X-API-Key: YOUR_API_KEY" ``` **Yanıt** ```json { "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: ```json { "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](errors-and-pagination.md) 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: | `error_code` | Durum | Ne oldu | |---|---|---| | `key_read_only` | `403` | Salt okunur bir anahtar yazma işlemi gerçekleştirmeye çalıştı. | | `key_scope_denied` | `403` | Anahtarın bu uç noktada veya bu yönetilen hesapta kullanılmasına izin verilmiyor — veya kapsamlı bir anahtar, API anahtarlarını yönetmeye çalıştı ki buna hiçbir zaman izin verilmez. | | `invalid_scopes` | `400` | İstenen kapsamlar `API Keys` bölümünü içeriyordu. Anahtarlar anahtarları yönetemez. | | `404` | `404` | Hesabınızda bu kimliğe sahip bir anahtar bulunmuyor. | --- ## Sonraki adımlar - [Kimlik Doğrulama](authentication.md) — 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ı](errors-and-pagination.md) — durum kodları ve 300 istek/dakika sınırı.