Tenants and Partners Reference

Admin endpoints for managing the tenancy hierarchy. For the concept overview, see Multi-tenancy.

Partners#

Super-admin only.

GET /v1/partners#

List all partners on the platform.

GET /v1/partners/{partner_id}#

Get partner details.

PUT /v1/partners/{partner_id}#

Update partner metadata.

json
{"name": "Partner Updated Name", "status": "active"}

Tenants#

Partner admin and super admin.

ScaiKey ↔ ScaiGrid binding — read before creating tenants. A ScaiGrid tenant is bound to its ScaiKey tenant by identical id: a tenant created in ScaiKey syncs into ScaiGrid under the same tnt_… id (one-way, ScaiKey → ScaiGrid). There is no separate link field; tenant_acme-style values in examples are slugs, not ids.

Provision in ScaiKey first, then let it sync. The POST /v1/tenants below creates a ScaiGrid-local tenant with a freshly generated id that is not bound to any ScaiKey tenant — using it for a tenant that also lives in ScaiKey produces a duplicate, unbound tenant. For the normal partner flow, create the tenant in ScaiKey and it appears here automatically; reserve POST /v1/tenants for ScaiGrid-only tenancy.

GET /v1/tenants#

List tenants visible to the caller. Partner admins see their partner's tenants; super admins see all.

Query params: limit, cursor, partner_id (filter), status.

POST /v1/tenants#

Create a tenant.

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",
    "partner_id": "partner_internal",
    "settings": {"default_model": "scailabs/poolnoodle-omni"}
  }'

GET /v1/tenants/{tenant_id}#

Get tenant details.

PUT /v1/tenants/{tenant_id}#

Update tenant.

json
{
  "name": "Acme Corp (updated)",
  "status": "active",
  "settings": {...}
}

Tenant templates#

Templates let you stamp out new tenants with consistent defaults (modules enabled, custom roles, pricing tier).

GET /v1/tenant-templates#

List available templates. Tenant-admin-level access.

POST /v1/tenant-templates#

Create a template.

json
{
  "name": "Standard SaaS Customer",
  "slug": "standard-saas",
  "description": "Default setup for new paying customers",
  "modules_enabled": ["scaibot", "scaimatrix"],
  "default_roles": [
    {"slug": "editor", "core_permissions": [...], "module_permissions": [...]}
  ],
  "budget_defaults": {"monthly_cost_limit": "1000.00"}
}

GET /v1/tenant-templates/{template_id}#

Get template details.

PUT /v1/tenant-templates/{template_id}#

Update a template.

DELETE /v1/tenant-templates/{template_id}#

Remove a template. Tenants previously created from it are unaffected.

POST /v1/tenant-templates/{template_id}/apply/{tenant_id}#

Apply a template to an existing tenant. Additive — enables listed modules, creates listed roles, sets budgets. Doesn't remove anything the tenant already has that's not in the template.

Suspending a tenant#

Set status: "suspended" on a tenant to immediately block all inference and most admin operations:

bash
curl -X PUT https://scaigrid.scailabs.ai/v1/tenants/{tenant_id} \
  -H "Authorization: Bearer $PARTNER_ADMIN_TOKEN" \
  -d '{"status": "suspended"}'

Users in a suspended tenant get 403 TENANT_SUSPENDED on authenticated requests. Unsuspend by setting status: "active".

Partner-level suspension (status: "suspended" on a partner) suspends all tenants under that partner.