Kimlik Doğrulama ve API Anahtarları

Purvisor AI Public API (v1) tek bir API anahtarıyla çalışır — oturum (login) cookie’si yok, OAuth akışı yok. Ayarlar’dan anahtarını üret, isteğine bir başlık ekle, Zapier/Make/n8n ya da kendi sunucun saniyeler içinde arama başlatabilir, kontak oluşturabilir. Anahtar sunucular arası (server-to-server) tasarlandığı için doğrulama tamamen bu tek değere dayanır; bu yüzden onu bir parola gibi saklamak kritik.

API anahtarı formatı

Her anahtar sabit bir önek (pk_live_) ile başlar ve ardından 48 hex karakter gelir:

pk_live_ + 48 hex karakter  =  toplam 56 karakter
└──────┘   └──────────────┘
 önek       crypto.randomBytes(24)

pk_live_ ile başlamayan hiçbir değer kabul edilmez — API isteği anahtarın önekini kontrol edip formatı tutmuyorsa daha veritabanına bakmadan reddeder. Anahtarın ilk 12 karakteri (pk_live_xxxx) panelde “prefix” olarak gösterilir; bu, hangi anahtarın aktif olduğunu gözle ayırt etmeni sağlayan maskelenmiş bir etikettir, tam anahtar değildir.

Kabul edilen üç yöntem

API anahtarını isteğe üç farklı şekilde geçirebilirsin. Purvisor AI bunları şu öncelik sırasıyla okur — biri bulunursa sonrakilere bakmaz:

1. X-API-Key başlığı (önerilen)

curl https://app.purvisor.ai/api/v1/me \
  -H "X-API-Key: pk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

2. Authorization: Bearer başlığı

curl https://app.purvisor.ai/api/v1/me \
  -H "Authorization: Bearer pk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

3. ?api_key= sorgu parametresi (yedek)

curl "https://app.purvisor.ai/api/v1/me?api_key=pk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

İpucu: Zapier bazen anahtarı hem başlığa hem sorguya koyar; bu durumda değerler , ile birleşir. Purvisor AI yalnızca ilk parçayı kullanır, yani çift gönderim sorun çıkarmaz.

Anahtarı oluşturma ve yenileme

Anahtarını panelden üretirsin — bu işlem oturum açıkken yapılır, API anahtarının kendisiyle değil.

{
  "apiKey": "pk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "keyPrefix": "pk_live_xxxx"
}

Tek aktif anahtar ve anlık geçersizleşme

Her kullanıcının tek bir aktif anahtarı vardır. “Yeniden Oluştur” dediğinde yeni anahtar eskisinin üzerine yazılır ve eski anahtar o anda geçersiz olur — eski anahtarla giden istekler artık 401 alır. Bir anahtar sızdıysa çözüm budur: yenile, eski anında ölür.

Anahtarlar nasıl saklanır? (güvenlik)

Purvisor AI anahtarları veritabanında düz metin olarak saklamaz — hash’lenmiş halde tutar. Saklanan değer şu biçimdedir:

hk_ + anahtarın ilk 12 karakteri + _ + base64url(sha256(anahtar))

Yani veritabanına erişen biri bile anahtarı geri türetip senin adına istek atamaz — hash’ten orijinal anahtar hesaplanamaz. İlk 12 karakter yalnızca panelde prefix göstermek için okunur tutulur. Bir istek geldiğinde Purvisor AI sunduğun anahtarı aynı yöntemle hash’leyip eşleşme arar; bu yüzden doğrulama düz metin karşılaştırması gerektirmez.

Bu, at-rest (dinlenme halinde) şifreleme sertleştirmesinin (G5) bir parçasıdır. Eski düz-metin anahtarlar ilk başarılı kullanımda otomatik olarak hash’e yükseltilir — anahtarın kendisi değişmez, senin bir şey yapmana gerek yoktur.

Doğrulama başarısız olduğunda

Anahtar eksik, formatı bozuk (pk_live_ ile başlamıyor) veya veritabanında eşleşmiyorsa, her v1 ucu tutarlı biçimde şunu döner:

HTTP/1.1 401 Unauthorized
Content-Type: application/json
 
{"error":"invalid_api_key"}

Bu yanıtı gördüğünde kontrol listesi:

Bağlantını test etmek için en hızlı yol GET /api/v1/me ucudur: 200 dönerse anahtar geçerlidir ve hesap kimliğini (id, email, name) görürsün.

İlgili