Kimlik doğrulama (authentication) — API anahtarı ile

Moonborn API'sine yapılan her istek çalışma alanına (workspace) bağlı bir API anahtarı (API key) ile doğrulanır. Bu sayfa anahtar oluşturma, yetki (scope) seçimi, IP izin listesi (allowlist), anahtar yenileme (rotation) akışını ve üretime çıkmadan önceki kontrolleri kapsar.

Bu sayfayı bitirdiğinde

• API anahtarını Bearer token olarak gönderebileceksin.
• Servis başına en az yetki (least privilege) ilkesiyle yetki seçebileceksin (read:personas, write:chat, ...).
• API üzerinden anahtar oluşturup gizli (secret) değeri bir kerelik kaydedebileceksin.
• IP izin listesi + sona erme tarihi + rotasyon akışını uygulayabileceksin.
• 429, 401, 403 hatalarını doğru yorumlayıp düzeltebileceksin.

Ön koşul: Çalışma alanı üyeliği + admin veya owner rolü (anahtar oluşturmak için).

Hızlı kullanım

API anahtarını Authorization başlığında (header) Bearer token olarak gönder:

curl https://api.moonborn.co/v1/personas \
  -H "Authorization: Bearer $MOONBORN_API_KEY"

Başlık formatı:

Authorization: Bearer sk_live_...

MOONBORN_API_KEY değerini ortam değişkeni (environment variable) olarak sakla:

export MOONBORN_API_KEY="sk_live_..."

API anahtarı oluşturma — arayüzden

1. Settings → API Keys sayfasına git
2. New key (yeni anahtar) seçeneğini aç
3. Anlaşılır bir ad ver: production-chat-runtime, staging-ingest, local-dev
4. Gerekli yetkileri (scope) seç (aşağıdaki tablo)
5. Üretildikten sonra anahtarı gizli anahtar yöneticisine (secret manager) yapıştır

Anahtar türleri — önek (prefix)

Test anahtarları üretim verisi için kullanılmamalı. Üretim anahtarları yerel geliştirme, demo veya istemci tarafı (client-side) kodda kullanılmamalı.

Yetkiler (scopes) — en az yetki ilkesi

Kanonik format: <action>:<resource> (read:personas, write:chat). Eski format personas:read artık kullanılmıyor — refactoring sonrası tüm sistem action:resource biçiminde.

Tam liste: Yetkiler.

Servis başına ayrı anahtar

Üretimde ana anahtarı (master key) paylaşma. Servis başına ayrı anahtar üret:

// Persona kataloğu okuyucusu (salt-okunur panel)
{ name: 'persona-catalog-reader', scopes: ['read:personas'] }
 
// Sohbet çalışma zamanı (üretim)
{ name: 'production-chat-runtime', scopes: ['read:personas', 'write:chat'] }
 
// CI kalite kapısı
{ name: 'ci-quality-gate', scopes: ['read:personas', 'write:personas'] }
 
// Finans ETL
{ name: 'finance-etl', scopes: ['read:billing'] }

Bir anahtar sızsa bile etki yarıçapı dar kalır.

API üzerinden anahtar oluştur

curl -X POST https://api.moonborn.co/v1/api_keys \
  -H "Authorization: Bearer $MOONBORN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "production-chat-runtime",
    "scopes": ["read:personas", "write:chat"],
    "expires_at": "2027-05-17T00:00:00Z"
  }'

Yanıt:

{
  "id": "key_01H...",
  "name": "production-chat-runtime",
  "prefix": "sk_live_",
  "scopes": ["read:personas", "write:chat"],
  "created_at": "2026-05-17T10:00:00Z",
  "expires_at": "2027-05-17T00:00:00Z",
  "secret": "sk_live_a1b2c3d4..."
}

Bazı çalışma alanlarında API üzerinden anahtar oluşturma kapalı olabilir; bu çalışma alanı ayarı.

IP izin listesi (Enterprise plan)

Enterprise planında anahtar kullanımı belirli IP aralıklarına sınırlandırılabilir:

curl -X PATCH https://api.moonborn.co/v1/api_keys/key_01H... \
  -H "Authorization: Bearer $MOONBORN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ip_allowlist": ["203.0.113.10/32", "198.51.100.0/24"]
  }'

İzin listesi dışından gelen istek geçerli anahtar kullansa bile 403 Forbidden döner. Üretim işçilerinin (worker) sabit NAT IP havuzu varsa zorunlu güvenlik katmanı.

Sona erme ve yenileme (expiry & rotation)

API anahtarlarına isteğe bağlı sona erme tarihi verilebilir:

• Geçici entegrasyonlar
• CI işleri (90 gün)
• Dış ajans erişimi (proje süresi)

Üretim anahtarlarını düzenli yenile:

1. Yeni anahtar oluştur (eski hâlâ aktif)
2. Uygulama ortam değişkenini yeni anahtarla güncelle (deploy)
3. Trafiğin yeni anahtara geçtiğini doğrula (denetim kaydından)
4. Eski anahtarı iptal et

60 dakikalık geçiş penceresi (grace window) süresince iki anahtar paralel geçerli:

curl -X POST https://api.moonborn.co/v1/api_keys/key_01H.../rotate \
  -H "Authorization: Bearer $MOONBORN_API_KEY"

Geçersiz kılma (override): api.api_keys.rotation_grace_minutes (varsayılan 60, en fazla 1440).

Hız limiti başlıkları

Her yanıt (başarı veya hata) şunları taşır:

X-RateLimit-Limit:     3000        # dakika başı üst sınır (plana göre)
X-RateLimit-Remaining: 2987        # mevcut pencerede kalan
X-RateLimit-Reset:     1747498200  # pencere sıfırlanma Unix zaman damgası

429'da ek olarak:

Retry-After: 12  # bir sonraki isteğin izinli olmasına saniye

Üretimde X-RateLimit-Remaining izle, üst sınırın %10'unun altındaysa yavaşla. Detay: Hız limitleri.

Yaygın hata kodları

Tüm 14 hata kodu: Hata kodları.

Yetki (scope) ile rol (RBAC) — birlikte çalışır

API anahtarı yetkisi ve çalışma alanı rolü iki ayrı kısıt katmanı. İkisi de geçerli olmalı:

Çakışma davranışı: Viewer rolündeki kullanıcı write:personas yetkili anahtar çıkarsa, anahtar kendi yetkisine + Viewer kısıtlamalarına bağlı kalır — pratikte 403. Detay: Yetkiler + Rol matrisi.

Üretime çıkmadan önce — kontrol listesi

• ☐ Gizli anahtarlar yalnızca sunucu tarafında kullanılıyor
• ☐ Anahtarlar .env veya gizli anahtar yöneticisinde (1Password, AWS SM, Vault, Doppler)
• ☐ Her servis için ayrı, dar kapsamlı anahtar
• ☐ Gereksiz write:config veya * yetkisi yok
• ☐ Üretim ve test anahtarları karıştırılmamış
• ☐ Anahtarlar loglara yazılmıyor
• ☐ Enterprise: IP izin listesi + sona erme tarihi aktif
• ☐ Yenileme zamanlaması (rotation cron) tanımlı (örn. 90 gün)
• ☐ Sızıntı yanıt el kitabı (response runbook) yazılı (yenile + denetim kaydını incele)

Plan gereksinimi

İlgili