Pular para o conteúdo

Autenticação

A API do Saiku Cloud usa autenticação por Bearer token. Toda requisição para https://api.saiku.bi/me/* carrega uma chave API que identifica o seu tenant.

URL base

https://api.saiku.bi

Emitindo uma chave API

  1. Abra a página de chaves API na barra lateral do dashboard.
  2. Dê à chave um nome que diga para que ela serve — production-agent, staging-bot.
  3. Opcionalmente liste cubos permitidos, separados por vírgula, para confinar a chave só a esses. Deixe em branco e a chave alcança todo cubo do tenant.
  4. Clique em Criar.
  5. Copie o segredo na hora — ele aparece uma vez só. Depois o dashboard guarda só o nome e o prefixo visível.

Fazendo uma requisição

Mande a chave no cabeçalho Authorization:

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

Resposta bem-sucedida:

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

Descobrindo a superfície

GET /me devolve a lista de endpoints disponíveis para você — um índice pequeno que dá para consultar antes de cravar caminhos no código:

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

Limites de taxa

Dois baldes — um orçamento de rajada por minuto e um sustentado por hora. Eles são por tenant, não por chave, então espalhar tráfego por várias chaves divide um orçamento em vez de multiplicá-lo.

TierPor minutoPor hora
Starter601 000
Team30010 000
Business1 00050 000
EnterpriseSob medidaSob medida

Não crave esses números no código — pergunte. GET /me/limits te diz o que está de fato valendo para a sua chave:

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

Toda resposta carrega o seu orçamento restante, então dá para segurar antes de ser recusado em vez de depois:

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

Ficar de olho nesses dois cabeçalhos é a diferença entre uma integração bem-educada e uma que descobre o limite batendo nele. Quando você bate mesmo assim, recebe 429 Too Many Requests com um cabeçalho Retry-After dizendo quando voltar.

Pagando por isso — o 402 cobre quase tudo

Quase toda a superfície /me/* exige uma assinatura ativa. “Ativa” é generoso — trialing e até past-due contam, então um cartão falhando não corta a sua integração no meio de um retry. Quando de fato não há assinatura, todo endpoint cobrado responde 402.

Quatro caminhos ficam abertos de qualquer jeito, e são os que precisam ficar:

IsentoPor quê
/me/billing/*Você precisa conseguir assinar em primeiro lugar.
/me/tenantO dashboard precisa da sua identidade só para renderizar.
/me/accountApagar a sua conta é um direito incondicional, pagando ou não.
/me/invites/*Aceitar um convite acontece antes de você ter um tenant pago.

Se a sua integração começa a devolver 402 em tudo, foi isso que aconteceu — confira GET /me/billing/state em vez da sua chave.

Formato da resposta de erro

Toda resposta de erro é JSON:

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

Códigos de erro comuns:

StatusCódigoSignificado
400variaRequisição ruim. O código nomeia o problema específico — missing_workspace, invalid_bucket — e message diz o que era esperado.
401unauthorizedChave API ausente ou inválida
402payment_requiredSem assinatura ativa — veja acima o que é isento
403forbiddenChave API válida mas sem permissão para este recurso
404not_foundO recurso não existe, ou não é visível para o seu tenant
429rate_limitedLimite por minuto ou por hora estourado

Rotacionando uma chave

  1. Na página de chaves API, clique em Criar chave para emitir uma nova. Dê a ela o mesmo rótulo da chave que você está rotacionando.
  2. Atualize o seu agente / integração para usar a chave nova.
  3. Depois de confirmar que a nova funciona em produção, volte à página de chaves API e revogue a antiga.

Não há indisponibilidade — as duas chaves valem ao mesmo tempo até você revogar a antiga.

O que vem depois

  • Use a API de billing para gerenciar a sua assinatura programaticamente.
  • Leia sobre isolamento de tenants para entender o que uma chave API consegue e não consegue alcançar.