API anahtarı yetkileri (scopes)
Bearer token'ları kısıtlayan 13 kanonik yetki (`<action>:<resource>` biçimi). Servis başı en az yetkili anahtarlar üret.
Her Moonborn API anahtarı açık bir yetki (scope) listesi taşır. Bir uç nokta için gerekli yetkisi eksik olan token 403 forbidden döner. Üretimde servis başına ayrı anahtar üretmek, ana anahtar paylaşımından çok daha güvenlidir — bir anahtar sızsa bile etki yarıçapı dar kalır.
Bu sayfayı bitirdiğinde
- 13 kanonik yetkiyi ve biçimini (
<action>:<resource>) bileceksin. - Tipik servis desenleri için doğru yetki birleşimini seçebileceksin.
- Yetkili anahtar oluşturma + yenileme (rotation) + IP izin listesi akışını uygulayabileceksin.
- Yetkilerin RBAC rolleriyle nasıl etkileştiğini netleştireceksin.
Ön koşul: Çalışma alanında admin veya owner rolü (API anahtarı oluşturmak için).
Tam yetki listesi
Kanonik biçim: <action>:<resource> (örn. read:personas, write:chat).
| Yetki | Verir |
|---|---|
* | Tüm yetkiler. Yalnızca Owner rolü. |
read:personas | Persona'ları listele, detay, lineage, DNA, ses oku |
write:personas | Persona yarat, refine, fork, arşivle, geri yükle |
read:chat | Sohbet oturumlarını listele, mesaj + bellek oku |
write:chat | Oturum başlat, mesaj gönder, oturum sonlandır |
read:marketplace | Pazaryeri yayınlarını ve koleksiyonları oku |
write:marketplace | Yayın gönder, fork, kur, incele |
read:billing | Abonelik, fatura, ödeme yöntemi, kullanım oku |
read:audit | Denetim kaydı girdilerini oku |
read:webhooks | Webhook'ları ve gönderimleri listele |
write:webhooks | Webhook yarat, güncelle, sil; gönderim yeniden gönder |
read:config | Yapılandırma maddelerini, anlık görüntüleri (snapshot), tanımları oku |
write:config | Yapılandırma yaz, kilitle, anlık görüntüden geri yükle |
En az yetki desenleri
Servis başına ayrı anahtar oluştur. Üretim ana anahtarını asla birden fazla servis arasında paylaşma.
| Servis | Yetkiler |
|---|---|
| Salt-okunur panel | read:personas, read:chat, read:audit |
| Gecelik senkronizasyon çalışanı | read:personas, read:chat, write:webhooks |
| CI kalite kapısı | read:personas, write:personas (denetim yeniden koşumu için) |
| Finans ETL | read:billing |
| Uyumluluk arşivleyici | read:audit, read:config |
| Persona üretim çalışanı | write:personas, read:personas |
| MCP IDE entegrasyonu | read:personas, write:chat |
| Slack bildirim botu | read:webhooks, write:webhooks |
Yetkili anahtar oluştur
const key = await client.apiKeys.create({
name: 'CI quality gate',
scopes: ['read:personas', 'write:personas'],
expiresAt: '2027-01-01T00:00:00Z',
});
console.log(key.plaintext);
// ⚠ Düz metin tam olarak BİR KEZ döner. Hemen sakla; ikinci okuma yok.IP izin listesi
Anahtarı belirli IP / CIDR'a kilitle (Team ve üzeri):
await client.apiKeys.update({
id: key.id,
ipAllowlist: ['203.0.113.0/24', '198.51.100.0/24'],
});İzin listesi dışından gelen istek yetkiden bağımsız 403 forbidden döner. Üretim çalışanlarının (worker) statik IP havuzu varsa bu desen zorunlu güvenlik katmanıdır.
Yenileme (rotation)
const rotated = await client.apiKeys.rotate({ id: key.id });
console.log(rotated.newPlaintext);
// Eski anahtar 60dk daha geçerli (geçiş penceresi)60 dakikalık geçiş penceresi süresince eski + yeni anahtar paralel geçerlidir. Tüketicileri güncelle, sonra eskisinin süresini bitir. Geçiş penceresi geçersiz kılma: api.api_keys.rotation_grace_minutes (varsayılan 60, en fazla 1440).
Yetki ile RBAC rolü — birlikte çalışır
API anahtarı yetkisi ve çalışma alanı RBAC rolü iki ayrı kısıt katmanıdır. İkisi de geçerli olmalı:
| Katman | Kapsamı | Örnek |
|---|---|---|
| API anahtarı yetkisi | API uç noktası erişimi | write:personas olmayan anahtar persona yaratamaz |
| RBAC rolü | Ürün-içi kullanıcı eylemleri | Viewer rolündeki kullanıcı persona düzenleyemez |
Plan gereksinimi
| Plan | Yetenek |
|---|---|
| Free | 5 anahtar, varsayılan yetki kümesi |
| Pro | Sınırsız anahtar, varsayılan yetki kümesi |
| Team | Özel yetki birleşimi + IP izin listesi + yenileme süresi ayarı |
| Enterprise | Özel yetkiler (çalışma alanına özgü kaynaklar) + organizasyon-geneli yetki envanteri |