Moonborn — Developers

API key scope'ları

Bearer token'ları kısıtlayan 13 kanonik scope. Servis başı en-az-yetki key'leri çıkar.

Her Moonborn API key'i açık bir scope listesi taşır. Bir endpoint için gerekli scope'u eksik olan token'lar 403 forbidden döner.

Tam set

Scope	Verir
`*`	Tüm scope'lar. Sadece Owner.
`read:personas`	Personaları listele, persona detay, lineage, DNA, voice oku
`write:personas`	Persona yarat, refine et, fork'la, archive'le, restore et
`read:chat`	Chat oturumlarını listele, mesaj + memory oku
`write:chat`	Oturum başlat, mesaj gönder, oturum sonlandır
`read:marketplace`	Marketplace listing'lerini, koleksiyonları listele + oku
`write:marketplace`	Listing'leri publish, fork, install, review
`read:billing`	Subscription, fatura, ödeme yöntemi, usage oku
`read:audit`	Audit log giriş'lerini oku
`read:webhooks`	Webhook'ları, delivery'leri listele
`write:webhooks`	Webhook yarat, güncelle, sil; delivery replay
`read:config`	Config item'larını, snapshot'ları, definition'ları oku
`write:config`	Config item yaz, item'ları kilitle, snapshot restore et

En-az-yetki pattern'leri

Servis	Scope'lar
Read-only dashboard	`read:personas`, `read:chat`, `read:audit`
Gecelik sync worker'ı	`read:personas`, `read:chat`, `write:webhooks`
Bir CI kalite gate'i	`read:personas`, `write:personas` (audit re-run'ları için)
Bir finans ETL'i	`read:billing`
Bir compliance archiver	`read:audit`, `read:config`
Persona-generation worker	`write:personas`, `read:personas`

Servis başı ayrı key çıkar. Production workload'ları arasında bir master key'i yeniden kullanma.

Scope'lu bir key çıkarmak

const key = await client.apiKeys.createApiKey({
  name: 'CI quality gate',
  scopes: ['read:personas', 'write:personas'],
  expiresAt: '2027-01-01T00:00:00Z',
});
 
console.log(key.plaintext);
// ⚠ Tam olarak bir kez döner. Hemen sakla; sonra elde edilemez.

IP allowlist

Ekstra bir katman için bir key'i IP allowlist ile eşle:

await client.apiKeys.updateApiKey({
  id: key.id,
  ipAllowlist: ['203.0.113.0/24'],
});

Allowlist dışındaki request'ler scope'tan bağımsız 403 forbidden döner.

Rotation

await client.apiKeys.rotateApiKey({ id: key.id });

Yeni bir plaintext döner; eski key konfigüre edilmiş grace period süresince geçerli kalır (api.api_keys.rotation_grace_minutes, default 60). Tüketicileri güncelle, sonra eski key'i expire et.

Tarif

5 key'e kadar: Free.
Sınırsız key: Pro.
Custom scope'lar / IP allowlist / rotation grace tuning: Team+.
Org başı scope inventory (custom scope'lar): Enterprise.