Zum Inhalt springen

Authentifizierung

Die Saiku-Cloud-API verwendet Bearer-Token-Authentifizierung. Jeder Request an https://api.saiku.bi/me/* trägt einen API-Key, der Ihren Tenant identifiziert.

Basis-URL

https://api.saiku.bi

Einen API-Key ausstellen

  1. Öffnen Sie die API-Keys-Seite aus der Dashboard-Seitenleiste.
  2. Geben Sie dem Key einen Namen, der sagt, wofür er ist — production-agent, staging-bot.
  3. Listen Sie optional erlaubte Cubes kommasepariert auf, um den Key auf genau diese zu beschränken. Lassen Sie es leer, und der Key erreicht jeden Cube im Tenant.
  4. Klicken Sie auf Erstellen.
  5. Kopieren Sie das Geheimnis sofort — es wird nur einmal gezeigt. Danach behält das Dashboard nur den Namen und das sichtbare Präfix.

Eine Anfrage stellen

Senden Sie den Key im Authorization-Header:

Terminal-Fenster
curl https://api.saiku.bi/me/tenant \
-H "Authorization: Bearer sk_abc123…"

Erfolgreiche Antwort:

{
"tenantId": "81e301f2-…",
"tenantSlug": "acme",
"tier": "team",
"connectionName": "production-warehouse"
}

Die Oberfläche entdecken

GET /me liefert die Liste der Ihnen zur Verfügung stehenden Endpunkte — ein kleiner Index, den Sie zuerst abfragen können, statt Pfade hart zu codieren:

{
"endpoints": [
"/me/tenant", "/me/tenant/deletion", "/me/upstream", "/me/limits",
"/me/cubes", "/me/analyze/cubes", "/me/members", "/me/workspaces",
"/me/api-keys", "/me/invites", "/me/audit", "/me/usage", "/me/schemas"
]
}

Rate-Limits

Zwei Eimer — ein Burst-Budget pro Minute und ein Dauer-Budget pro Stunde. Sie gelten pro Tenant, nicht pro Key, Traffic über mehrere Keys zu verteilen teilt sich also ein Budget, statt es zu vervielfachen.

TarifPro MinutePro Stunde
Starter601 000
Team30010 000
Business1 00050 000
EnterpriseIndividuellIndividuell

Codieren Sie diese Zahlen nicht hart — fragen Sie. GET /me/limits sagt Ihnen, was für Ihren Key tatsächlich gilt:

{ "enabled": true, "profile": "starter-default", "perMinute": 60, "perHour": 1000 }

Jede Antwort trägt Ihr verbleibendes Budget, Sie können also abbremsen, bevor Sie abgewiesen werden, statt danach:

X-RateLimit-Remaining-Minute: 60
X-RateLimit-Remaining-Hour: 1000

Diese beiden Header zu beobachten ist der Unterschied zwischen einer wohlerzogenen Integration und einer, die das Limit entdeckt, indem sie dagegenläuft. Wenn Sie es doch treffen, bekommen Sie 429 Too Many Requests mit einem Retry-After-Header, der sagt, wann Sie wiederkommen sollen.

Bezahlen dafür — 402 deckt fast alles ab

Fast die gesamte /me/*-Oberfläche erfordert ein aktives Abonnement. „Aktiv” ist großzügig gemeint — trialing und sogar past-due zählen beide, eine fehlschlagende Karte schneidet Ihre Integration also nicht mitten im Retry ab. Sobald es wirklich kein Abonnement gibt, antwortet jeder abgerechnete Endpunkt mit 402.

Vier Pfade bleiben unabhängig davon offen, und es sind die, die es müssen:

AusgenommenWarum
/me/billing/*Sie müssen überhaupt abonnieren können.
/me/tenantDas Dashboard braucht Ihre Identität, um sich überhaupt zu rendern.
/me/accountIhr Konto zu löschen ist ein unbedingtes Recht, bezahlt oder nicht.
/me/invites/*Eine Einladung anzunehmen passiert, bevor Sie einen bezahlten Tenant haben.

Wenn Ihre Integration auf breiter Front 402 zurückzugeben beginnt, ist genau das passiert — prüfen Sie GET /me/billing/state statt Ihren Key.

Format der Fehlerantwort

Jede Fehlerantwort ist JSON:

{
"error": "payment_required",
"message": "This feature requires an active subscription or trial. Visit /billing to start your 14-day trial."
}

Häufige Fehlercodes:

StatusCodeBedeutung
400variiertFehlerhafter Request. Der Code benennt das konkrete Problem — missing_workspace, invalid_bucket — und message sagt, was erwartet wurde.
401unauthorizedAPI-Key fehlt oder ist ungültig
402payment_requiredKein aktives Abonnement — was ausgenommen ist, steht oben
403forbiddenAPI-Key gültig, aber ohne Berechtigung für diese Ressource
404not_foundRessource existiert nicht oder ist für Ihren Tenant nicht sichtbar
429rate_limitedLimit pro Minute oder pro Stunde überschritten

Einen Key rotieren

  1. Klicken Sie auf der API-Keys-Seite auf Key erstellen, um einen neuen auszustellen. Geben Sie ihm dasselbe Label wie dem Key, den Sie rotieren.
  2. Stellen Sie Ihren Agenten / Ihre Integration auf den neuen Key um.
  3. Sobald Sie bestätigt haben, dass der neue Key in der Produktion funktioniert, kehren Sie zur API-Keys-Seite zurück und widerrufen den alten.

Es gibt keine Ausfallzeit — beide Keys sind gleichzeitig gültig, bis Sie den alten widerrufen.

Wie geht es weiter?

  • Nutzen Sie die Billing-API, um Ihr Abonnement programmatisch zu verwalten.
  • Lesen Sie über Tenant-Isolation, um zu verstehen, was ein API-Key erreichen kann und was nicht.