Moonborn — Developers

API-Key-Scopes

Die 13 kanonischen Scopes, die Bearer-Tokens einschränken. Stelle Least-Privilege-Keys pro Service aus.

Jeder Moonborn-API-Key trägt eine explizite Scope-Liste. Tokens, denen der für einen Endpoint erforderliche Scope fehlt, geben 403 forbidden zurück.

Das volle Set

Scope	Gewährt
`*`	Alle Scopes. Nur Owner.
`read:personas`	Personas auflisten, Persona-Details, Lineage, DNA, Voice lesen
`write:personas`	Personas erstellen, refinen, forken, archivieren, restoren
`read:chat`	Chat-Sessions auflisten, Messages + Memory lesen
`write:chat`	Sessions starten, Messages senden, Sessions beenden
`read:marketplace`	Marketplace-Listings, Collections auflisten + lesen
`write:marketplace`	Listings publishen, forken, installieren, reviewen
`read:billing`	Subscription, Rechnungen, Zahlungsmethoden, Usage lesen
`read:audit`	Audit-Log-Einträge lesen
`read:webhooks`	Webhooks, Deliveries auflisten
`write:webhooks`	Webhooks erstellen, updaten, löschen; Deliveries replayen
`read:config`	Config-Items, Snapshots, Definitions lesen
`write:config`	Config-Items schreiben, Items locken, Snapshots restoren

Least-Privilege-Patterns

Service	Scopes
Read-only-Dashboard	`read:personas`, `read:chat`, `read:audit`
Nightly-Sync-Worker	`read:personas`, `read:chat`, `write:webhooks`
CI-Quality-Gate	`read:personas`, `write:personas` (für Audit-Re-Runs)
Finance-ETL	`read:billing`
Compliance-Archiver	`read:audit`, `read:config`
Persona-Generation-Worker	`write:personas`, `read:personas`

Stelle separate Keys pro Service aus. Reuse keinen einzelnen Master- Key über Production-Workloads.

Einen scoped Key ausstellen

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);
// ⚠ Genau einmal zurückgegeben. Sofort speichern; später nicht abrufbar.

IP-Allowlist

Paare einen Key mit einer IP-Allowlist für eine zusätzliche Schicht:

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

Requests von außerhalb der Allowlist geben unabhängig vom Scope 403 forbidden zurück.

Rotation

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

Gibt einen neuen Plaintext zurück; der alte Key bleibt für die konfigurierte Grace-Period gültig (api.api_keys.rotation_grace_minutes, Standard 60). Update Konsumenten, dann lass den alten Key ablaufen.

Tarif

Bis zu 5 Keys: Free.
Unbegrenzte Keys: Pro.
Custom-Scopes / IP-Allowlist / Rotation-Grace-Tuning: Team+.
Per-Org-Scope-Inventar (Custom-Scopes): Enterprise.

Ehrlicher Scope

API-Key-Scopes schränken API-Zugriff ein. Workspace-Level RBAC-Rollen schränken User-Aktionen innerhalb des Produkts ein. Sie überlappen sich — ein write:personas-Key, ausgestellt von einem Viewer-Rollen-Nutzer, erbt die Read-Constraints des Viewers zusätzlich zum Scope des Keys.