Multi-tenancy

ScaiGrid is multi-tenant from the ground up. Every request runs inside a three-level hierarchy:

flowchart LR Partner[Partner] TenantA[Tenant A] TenantB[Tenant B] User1[User 1] User2[User 2] User3[User 3] User4[User 4] Partner --> TenantA Partner --> TenantB TenantA --> User1 TenantA --> User2 TenantA --> User3 TenantB --> User4

You cannot opt out of this structure. Even a single-tenant deployment has exactly one partner and one tenant; the hierarchy is just collapsed to a minimal shape.

The three levels#

Partner#

Top level. A partner is usually a reseller or white-label deployer — a company that resells ScaiGrid to its own customers. Partners aggregate accounting across their tenants, get their own billing perspective, and can have partner-level admins who manage multiple tenants at once.

If you're self-hosting ScaiGrid for your own use, you have exactly one partner (often called internal or your company name). You rarely think about it.

Tenant#

A tenant is a workspace. Most ScaiGrid resources scope to a tenant — users belong to tenants, models are visible per tenant, API keys are tenant-scoped, accounting rolls up per tenant. If you're a SaaS platform, each of your customers is a tenant.

A tenant has a slug (acme-corp), a display name, a status (active / suspended), and optional settings. It belongs to a partner.

User#

An individual human or service identity. A user belongs to exactly one tenant. They have roles (see Roles and Permissions) that determine what they can do within that tenant.

Users come from ScaiKey (our identity provider). Humans sign in via SSO; services authenticate via API keys tied to a user.

How scoping works in practice#

Every authenticated request carries the caller's tenant and user. Handlers scope their database queries accordingly. A request like GET /v1/models only returns models visible to the caller's tenant — tenant-specific models they own, partner-level models their partner allows, and platform-level models available to everyone.

Permissions are checked at every level. A tenant admin sees their tenant's users; a partner admin sees every tenant under their partner; a super admin sees everything. You don't need application code to enforce these — the permission guards on each endpoint do it.

Accounting is hierarchical. Usage events tag all three levels (partner, tenant, user). You can query spend at any level. Budgets enforce at any level. A tenant running over its cap blocks its users; a partner running over its cap blocks its tenants.

Rate limits are per-level. API keys have their own limits, users have limits, tenants have limits, partners have limits. A runaway user can't take down the tenant; a runaway tenant can't take down the partner. See Rate Limiting.

Which endpoints are scoped how#

Endpoint family	Scope
`/v1/inference/*`	Tenant + user — the caller can only use models they have access to
`/v1/models`	Tenant — returns only models visible to the caller's tenant
`/v1/users`	Tenant — a tenant admin sees only their tenant's users
`/v1/tenants`	Partner or platform — partner admin sees tenants in their partner
`/v1/partners`	Platform — super admin only
`/v1/accounting/*`	Configurable — caller needs `accounting:view_own`, `accounting:view_tenant`, or `accounting:view_partner`
`/v1/audit-log`	Tenant + above, depending on role

Cross-tenant data is impossible by design#

There is no endpoint that lets a tenant user read another tenant's data. Period. The permission system and the query-time scoping ensure that even an admin-UI-induced bug can't leak across tenants. A super admin can see everything, but that's the only exception, and their actions are always recorded in the audit log.

If you find yourself wanting to share something across tenants (a model, a skill, a persona), the right mechanism is to scope it at the partner or platform level. ScaiGrid has explicit scope types for this.

Setting up tenants and users#

Tenants are created by partner or platform admins. Most common flow:

bash
curl -X POST https://scaigrid.scailabs.ai/v1/tenants \
  -H "Authorization: Bearer $PARTNER_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Acme Corp", "slug": "acme-corp"}'

Users are either provisioned manually by a tenant admin or show up automatically the first time they authenticate via ScaiKey SSO (depending on your group-mapping configuration).

Tenant templates#

A tenant template packages up default settings, module enablement, and a starting set of custom roles. Apply it to a newly-created tenant to get a consistent configuration:

bash
curl -X POST https://scaigrid.scailabs.ai/v1/tenant-templates/{template_id}/apply/{tenant_id} \
  -H "Authorization: Bearer $TENANT_ADMIN_TOKEN"

Useful for SaaS platforms that onboard new customers often.

What's next#

Roles and Permissions — who can do what within a tenant.
Accounting and Budgets — how usage rolls up the hierarchy.
Tenants and Partners Reference — admin endpoints.