---
title: Tenants and Partners Reference
path: reference/tenants-and-partners
status: published
---

# Tenants and Partners Reference

Admin endpoints for managing the tenancy hierarchy. For the concept overview, see [Multi-tenancy](../03-core-concepts/01-multi-tenancy.md).

## 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.

### 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.

## Related

- [Multi-tenancy](../03-core-concepts/01-multi-tenancy.md)
- [Roles and Permissions](../03-core-concepts/02-roles-and-permissions.md)
- [Users and Access](./02-users-and-access.md)