İçeriğe Geç
Dokümanlar / Başlarken

API Anahtarı

Bu sayfada

API Anahtarı

Regvion API anahtarları kendi kendine kayıt yoluyla alınmaz — satış süreci sonunda Regvion admin paneli üzerinden sizin için oluşturulur. Bu sayfa anahtarın yaşam döngüsünü, nasıl teslim alındığını ve nasıl güvende tutulacağını anlatır.

Anahtarı nasıl alırsınız

  1. Satış ekibi tenant'ınızı portalda oluşturur ve iletişim e-posta adresinize bir davet gönderir.
  2. E-postadaki "API Anahtarını Göster" bağlantısı sizi https://portal.regvion.com/api-key/reveal?token=... adresine götürür.
  3. Açılan sayfada bir onay butonu vardır — butonu tıklayana kadar anahtar gösterilmez. (Bu adım kasıtlıdır: Gmail/Outlook gibi e-posta önizleyicileri bağlantıları otomatik olarak ziyaret eder; GET isteği token'ı yakmaz, yalnızca POST yakar.)
  4. Butona tıkladığınız anda anahtar bir kez ekranda gösterilir. Sayfadan ayrıldığınızda veya yenilediğinizde token harcanmış olur ve anahtar bir daha gösterilmez.

Anahtar biçimi

rgv_live_<64 karakter hex>

Örn: rgv_live_a1b2c3... (toplam 73 karakter). Sunucuda yalnızca SHA-256 hash'i saklanır; orijinal anahtar sunucuda bile yoktur. Kaybolursa yeniden gösterilemez — rotate etmek gerekir.

İstek başlığı

X-API-Key: rgv_live_<key>

Her isteğe eklenir. Eksik veya yanlışsa 401 UNAUTHORIZED döner. Büyük/küçük harf duyarlıdır.

IP kısıtlaması (izinli IP listesi)

Geçerli bir anahtar tek başına yeterli olmayabilir: müşteri hesabınıza bir izinli IP/CIDR listesi tanımlanabilir ve bu liste her istekte kontrol edilir. Listede olmayan bir adresten gelen istek, anahtar geçerli olsa bile 403 + IP_NOT_ALLOWED alır:

{
  "success": false,
  "error": {
    "code": "IP_NOT_ALLOWED",
    "message": "Your IP is not in this customer's allowlist. Contact your administrator."
  }
}
  • Liste * içeriyorsa her IP kabul edilir (yeni hesapların varsayılanı).
  • Liste boş bırakılırsa hiçbir IP kabul edilmez (fail-closed). Bu bir kilitlenme durumudur ve yalnızca Regvion yöneticisi düzeltebilir.
  • Girdiler tek IP (203.0.113.7) veya CIDR (203.0.113.0/24) olabilir; IPv4 ve IPv6 desteklenir.
  • Sunucu isteğin çıkış IP'sini görür: NAT geçidi, proxy veya bulut bölgesi değişikliği yeni bir çıkış IP'si demektir. Yeni adresi devreye almadan önce listeye eklettirin.
  • Liste güncellemesi anında yürürlüğe girmez: kimlik doğrulama bilgisi ağ geçidinde 5 dakika önbelleklenir, dolayısıyla değişiklik en geç ~5 dakika içinde uygulanır. IP listesini daraltırken bu pencereyi hesaba katın.
  • Bu kontrol oran sınırından önce çalışır; reddedilen bir istek kotanızdan düşülmez ve yanıtı X-RateLimit-* başlıklarını taşımaz.

Anahtarı nereye saklayın

  • Üretim: HashiCorp Vault, AWS Secrets Manager, Azure Key Vault, GCP Secret Manager gibi yönetilen secret store.
  • CI/CD: GitHub Actions Secrets / GitLab CI Variables.
  • Geliştirici makinesi: .env dosyası (.gitignore içinde olmak kaydıyla) veya OS keychain.

Asla yapmayın:

  • Anahtarı kaynak kodunda sabitlemek.
  • Anahtarı tarayıcıda çalışan JavaScript bundle'ına katıştırmak (sunucudan sunucuya tasarlanmıştır; tarayıcı isteklerinde CORS headers eklenmez).
  • Anahtarı Slack/e-posta/issue yorumlarında düz metin olarak paylaşmak.
  • Anahtarı public git deposuna commitlemek — rgv_live_ öneki gitleaks/trufflehog gibi tarayıcıların hemen yakaladığı bir imzadır.

Yaşam döngüsü

Her anahtarın üç durumu vardır:

Active (varsayılan 365 gün)

Normal çalışma. İstekler 200 döner. Tier izniniz yettiği sürece her uç noktaya erişirsiniz.

Expiring (son kullanma tarihinden SONRAKİ 7 gün — ek süre)

Son kullanma tarihi geçtikten sonraki 7 gün (ek süre / grace period) boyunca istekler hâlâ başarılı olur, ancak yanıt aşağıdaki başlıkları taşır:

X-API-Key-Status: renewal-required
X-API-Key-Expires-In: 4d

X-API-Key-Expires-In ek sürenin bitimine kalan gün sayısıdır — anahtarın son kullanma tarihine kalan gün değil. Son kullanma tarihinden önce hiçbir uyarı başlığı gönderilmez.

Bu pencerede admin'inizden yeni anahtar oluşturmasını isteyin. Yeni anahtarı paralel kullanıma aldıktan sonra eski anahtar süresiz pasife alınabilir.

Üretimde mutlaka: X-API-Key-Status başlığı bir erken uyarı değildir — göründüğü anda anahtarınızın süresi çoktan dolmuştur ve yalnızca 7 günlük ek süreniz kalmıştır. İzleme platformunuzda (Datadog, Grafana, New Relic) bu başlığa yine de alarm kurun; ama proaktif önlem için anahtarın son kullanma tarihini kendi takviminizde takip edin. Ek süre dolduğunda servisiniz 403 almaya başlar.

Expired (grace süresi de dolduktan sonra)

403 Forbidden + KEY_EXPIRED hata kodu. Tüm istekler reddedilir. Admin yeni anahtar rotate etmek zorundadır.

{
  "success": false,
  "error": {
    "code": "KEY_EXPIRED",
    "message": "API key has expired. Contact your administrator to renew."
  }
}

Rotasyon

Rotasyon Regvion yönetim panelinden yapılır. Yeni anahtar oluşturulduğunda:

  1. Yeni anahtar için de aynı reveal e-postası iletişim adresine gönderilir.
  2. Eski anahtar hemen iptal edilmez — siz iptal isteyene kadar aktif kalabilir.
  3. Üretime yeni anahtarı dağıtın (config/secret rotate).
  4. Eski anahtarı iptal edin — en fazla 5 dakikalık önbellek gecikmesiyle istekleri reddetmeye başlar. Acil iptal gerekiyorsa [email protected] adresine yazın.

Birden fazla anahtar

Enterprise müşterileri aynı anda birden çok anahtara sahip olabilir (kesintisiz rotasyon için). Her anahtar aynı müşteriye, aynı tier'a, aynı izin setine bağlıdır — sadece rotasyon cihazı olarak ayrılırlar.