Tenants Routes

Full tenant lifecycle management. Tenants represent isolated organisations or workspaces within a multi-tenant deployment. Successful writes invalidate the dashboard metrics cache.

Routes

GET /api/admin/tenants

Paginated tenant list with search, filters, and sorting.

Query Parameters

Querystring values are type-coerced by JSON Schema validation — ?page=2&limit=20 arrives as numbers.

Response

{
  "success": true,
  "data": [
    { "id": "tnt_abc", "slug": "acme-corp", "name": "Acme Corp", "status": "active", "plan": "pro", "createdAt": "2026-01-15T09:00:00.000Z" }
  ],
  "meta": { "page": 1, "limit": 20, "total": 5, "totalPages": 1 }
}

POST /api/admin/tenants

Create a tenant. Returns 201.

Body Fields

New tenants are created with status: "active".

GET /api/admin/tenants/:id

Fetch a single tenant, including a userCount. Returns 404 when the tenant does not exist.

PUT /api/admin/tenants/:id

Update a tenant. Body accepts name, slug, plan, planId, settings (all optional).

DELETE /api/admin/tenants/:id

Permanently delete a tenant. Returns 404 when the tenant does not exist. Response: { "success": true, "data": null }.

POST /api/admin/tenants/:id/suspend

Suspend a tenant. Optional body field reason (string) is stored as suspendedReason. Sets status: "suspended" and suspendedAt.

POST /api/admin/tenants/:id/activate

Re-activate a suspended tenant: sets status: "active" and clears suspendedAt/suspendedReason.

PUT /api/admin/tenants/:id/plan

Change the tenant's plan.

Body Fields

Returns 404 when the tenant does not exist. The response includes previousPlan for display.

PUT /api/admin/tenants/:id/settings

Update tenant settings. Settings are merged with the existing object (including a nested features merge), not replaced.

Body Fields

Returns 404 when the tenant does not exist.

AI Context

package: "@xenterprises/fastify-xadmin"
routes:
  - GET /api/admin/tenants — paginated list; query: page, limit (1-100), sort (name/createdAt/updatedAt/status/plan), order, search, status, plan
  - POST /api/admin/tenants — create (name required); 201
  - GET /api/admin/tenants/:id — single tenant + userCount; 404
  - PUT /api/admin/tenants/:id — update name/slug/plan/planId/settings
  - DELETE /api/admin/tenants/:id — permanent delete; 404
  - POST /api/admin/tenants/:id/suspend — body: reason?; sets status suspended
  - POST /api/admin/tenants/:id/activate — clears suspension
  - PUT /api/admin/tenants/:id/plan — body: planId (required); 404
  - PUT /api/admin/tenants/:id/settings — merges settings + featureFlags; storageLimit; 404
permissions: tenants:read/create/update/delete/manage
side-effects: writes audit-log entries; invalidate dashboard metrics cache

See Also

• Users Routes — manage the users belonging to a tenant
• Dashboard Routes — tenant counts feed dashboard metrics
• Audit Log Routes — every tenant mutation is recorded