Kimlik doğrulama
Sessions API'ye ve Dosyalar uç noktasına yapılan her çağrı, çalışma alanınızdan bir API anahtarı ister. Anahtarı bearer token olarak gönderirsiniz. Anahtar hangi çalışma alanında olduğunuzu ve neler yapabileceğinizi zaten söyler; başka bir kurulum gerekmez.
Gelen webhook'lar ve web sitesi sohbeti API'si API anahtarı kullanmaz; bkz. kendi kuralları.
Anahtar alın
Anahtarları bir yönetici Ayarlar → API anahtarları bölümünde oluşturur:
- Bir ad girin, ör. "Mobil uygulama sunucusu".
- Yalnızca okuma ya da Okuma ve yazma seçin.
- Anahtar oluştur'a tıklayın ve anahtarı kopyalayın. Yalnızca bir kez gösterilir.
Anahtarlar psk_ ile başlar. Yönetmek, yenilemek ve iptal etmek için bkz. API anahtarları.
Anahtarı gönderin
Anahtarı Authorization başlığına, Bearer ve bir boşluktan sonra koyun:
GET /api/agents/66f1c2a9e4b0a1d2c3e4f567/sessions HTTP/1.1
Host: peki.ai
Authorization: Bearer psk_anahtariniz
curl ile:
curl https://peki.ai/api/agents/66f1c2a9e4b0a1d2c3e4f567/sessions \
-H "Authorization: Bearer $PEKI_API_KEY"
JavaScript ile (Node.js 18 ve sonrası ya da fetch olan herhangi bir ortam):
const res = await fetch('https://peki.ai/api/agents/66f1c2a9e4b0a1d2c3e4f567/sessions', {
headers: { Authorization: `Bearer ${process.env.PEKI_API_KEY}` },
});
if (!res.ok) throw new Error(`Peki API ${res.status}: ${await res.text()}`);
const sessions = await res.json();
Çalışma alanı başlığı
Çalışma alanı başlığına gerek yoktur: anahtar tek bir çalışma alanına aittir ve her çağrı orada çalışır. Yine de x-workspace-id gönderirseniz aynı çalışma alanı olmalıdır; değilse çağrı 403 API key belongs to another workspace ile reddedilir.
Erişim düzeyleri
| Anahtar erişimi | Hangi rolle çalışır | İzin verilenler |
|---|---|---|
| Yalnızca okuma | İzleyici | GET uç noktaları: oturumları listeleme ve okuma, mesajları okuma, dosya indirme. |
| Okuma ve yazma | Düzenleyici | Yukarıdakilerin hepsi, ayrıca oturum başlatma, mesaj gönderme, dosya yükleme, oturumu yeniden adlandırma, puanlama ve çözüldü olarak kapatma. |
Bir anahtarın yetkisi hiçbir zaman düzenleyiciden fazla olmaz. Yönetici ya da sahip gerektiren uç noktalar ve yalnızca kişilere yönelik uç noktalar (üyeler, API anahtarları, onaylar, Copilot) her anahtarı reddeder.
Sessions API sayfasındaki her uç nokta gereken erişimi belirtir.
Hatalar
| Durum | Mesaj | Neden | Ne yapmalı |
|---|---|---|---|
401 | Sign in required | Authorization başlığı yok ya da Bearer ile başlamıyor. | Authorization: Bearer psk_… gönderin. |
401 | Invalid API key | Anahtar yanlış, eksik ya da iptal edilmiş. | Anahtarın tamamını kopyaladığınızı kontrol edin; iptal edildiyse yenisini oluşturun. |
403 | Requires editor role | Yalnızca okuma anahtarı bir şeyi değiştiren uç noktayı çağırdı. | Okuma ve yazma anahtarı kullanın. |
403 | Not available to API keys | Uç nokta Peki paneline giriş yapmış kişiler içindir. | Bunu Peki panelinde yapın. |
403 | API key belongs to another workspace | Başka bir çalışma alanının x-workspace-id değerini gönderdiniz. | Başlığı göndermeyin. |
Örnek:
{ "statusCode": 401, "message": "Invalid API key", "error": "Unauthorized" }
Anahtarları gizli tutun
- API'yi sunucunuzdan çağırın, asla tarayıcıdan ya da mobil uygulamadan çağırmayın. Anahtarı gören herkes onu kullanabilir.
- Anahtarları kaynak kodda değil, platformunuzun gizli bilgi deposunda ya da ortam ayarlarında tutun.
- Her sistem için ayrı anahtar kullanın; böylece birini diğerlerine dokunmadan iptal edebilirsiniz.
Arka ucu olmayan bir web sayfasında sohbet gerekiyorsa, herkese açık olacak şekilde tasarlanan Web sitesi sohbeti API'sini kullanın.
API anahtarı kullanmayan yüzeyler
| Yüzey | Kimlik bilgisi |
|---|---|
| Gelen webhook'lar | Webhook URL'sinin kendisi gizlidir (/hooks/whk_…). Otomasyonu yalnızca gerçek gönderen başlatabilsin diye imza kontrolünü açın. |
| Web sitesi sohbeti API'si | Widget'ın herkese açık anahtarı (pw_…) ve rastgele bir ziyaretçi kimliği. Yalnızca o ziyaretçinin kendi konuşmasına ve yalnızca izin verdiğiniz sitelerden erişebilir. |