Authentication

The Saiku Cloud API uses Bearer-token authentication. Every request to https://api.saiku.bi/me/* carries an API key that identifies your tenant.

Tip

Connecting an LLM chat client (Claude Desktop, claude.ai, Cursor) to the MCP server? Those clients don’t need an API key — they authenticate over the OAuth 2.1 connector (self-serve, Team and above). See Connecting an agent. API keys are for programmatic and REST access.

Base URL

https://api.saiku.bi

Minting an API key

Tip

Each API key is bound to your tenant on the server side. Don’t share keys outside your team — rotate immediately if a key is ever exposed.

1. Open the API keys page from the dashboard sidebar.
2. Give the key a name that says what it’s for — production-agent, staging-bot.
3. Optionally list allowed cubes, comma-separated, to confine the key to just those. Leave it blank and the key reaches every cube in the tenant.
4. Click Create.
5. Copy the secret immediately — it’s shown once. Afterwards the dashboard keeps only the name and the visible prefix.

Making a request

Send the key in the Authorization header:

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

Successful response:

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

Discovering the surface

GET /me returns the list of endpoints available to you — a small index you can hit first rather than hard-coding paths:

{
  "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

Two buckets — a per-minute burst budget and a per-hour sustained one. They’re per tenant, not per key, so spreading traffic across several keys shares one budget rather than multiplying it.

Tier	Per minute	Per hour
Starter	60	1 000
Team	300	10 000
Business	1 000	50 000
Enterprise	Custom	Custom

Don’t hard-code those numbers — ask. GET /me/limits tells you what’s actually in force for your key:

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

Every response carries your remaining budget, so you can back off before you get refused rather than after:

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

Watching those two headers is the difference between a well-behaved integration and one that discovers the limit by hitting it. When you do hit it, you get 429 Too Many Requests with a Retry-After header saying when to come back.

Paying for it — 402 covers nearly everything

Almost the whole /me/* surface requires an active subscription. “Active” is generous — trialing and even past-due both count, so a failing card doesn’t cut your integration off mid-retry. Once there’s genuinely no subscription, every billed endpoint answers 402.

Four paths stay open regardless, and they’re the ones that have to:

Exempt	Why
/me/billing/*	You need to be able to subscribe in the first place.
/me/tenant	The dashboard needs your identity to render at all.
/me/account	Deleting your account is an unconditional right, paid or not.
/me/invites/*	Accepting an invite happens before you have a paid tenant.

If your integration starts returning 402 across the board, that’s what happened — check GET /me/billing/state rather than your key.

Error response shape

Every error response is JSON:

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

Common error codes:

Status	Code	Meaning
400	varies	Bad request. The code names the specific problem — missing_workspace, invalid_bucket — and message says what was expected.
401	unauthorized	API key missing or invalid
402	payment_required	No active subscription — see above for what’s exempt
403	forbidden	API key valid but lacks permission for this resource
404	not_found	Resource doesn’t exist, or isn’t visible to your tenant
429	rate_limited	Per-minute or per-hour limit exceeded

Caution

One exception worth coding around. The envelope above covers errors Saiku raises itself. A request to a path that doesn’t exist at all — or the wrong HTTP method on one that does — is answered by the framework instead, in a different shape:

{ "timestamp": "…", "status": 404, "error": "Not Found", "path": "/me/nope" }

Note error there is a human-readable string ("Not Found"), not a code ("not_found"). So a client branching on error === 'not_found' will match a missing schema but not a typo’d URL. Branch on the HTTP status first, and treat error as a refinement.

Rotating a key

1. On the API keys page, click Create key to mint a new one. Give it the same label as the key you’re rotating.
2. Update your agent / integration to use the new key.
3. Once you’ve confirmed the new key works in production, return to the API keys page and revoke the old one.

There’s no downtime — both keys are valid simultaneously until you revoke the old one.

What’s next

• Use the Billing API to manage your subscription programmatically.
• Read about tenant isolation to understand what an API key can and can’t reach.