Tenant Management API

Tenant CRUD, hierarchy management, settings, and logo upload for multi-tenant operations.

The Tenant Management API provides full lifecycle management for tenants in the multi-tenant hierarchy. Parent tenants can manage their children, and each tenant has isolated settings, branding, and resource limits.

Setting	Value	Description
Base URL	/api/v1/Tenants	All tenant management endpoints base path
Auth Required	Yes — Bearer Token	Requires authentication and relevant permissions
Permission Prefix	tenants.*	Standard actions map to tenants.view, tenants.create, tenants.update, tenants.delete
Tenant Gating	Enforced	Admins can only see/manage their own tenant and child/descendant tenants

Tenant CRUD

Method	Endpoint	Description	Auth
GET	`/api/v1/Tenants`	List all tenants visible to the current admin's scope, with pagination.	🔒 Required
GET	`/api/v1/Tenants/{id}`	Get full tenant details including settings, statistics, and hierarchy info.	🔒 Required
POST	`/api/v1/Tenants`	Create a new child tenant under the current admin's tenant.	🔒 Required
PUT	`/api/v1/Tenants/{id}`	Update tenant name, slug, and basic information.	🔒 Required
DELETE	`/api/v1/Tenants/{id}`	Soft-delete a tenant. Active admins and users are deactivated.	🔒 Required

GET /api/v1/Tenants/{id} — ResponseJSON

{
  "id": "tenant-uuid-f8e7d6c5",
  "name": "Acme Corporation",
  "code": "ACME",
  "logoUrl": "/uploads/tenants/acme-logo.png",
  "parentTenantId": null,
  "isActive": true,
  "description": "Acme Corporation global HQ",
  "address": "123 Main St, New York, NY",
  "createdAt": "2026-01-01T00:00:00Z"
}

Hierarchy & Statistics

Tenants form a tree hierarchy where parent tenants can see and manage their children. The hierarchy endpoint returns the full tree structure, while other endpoints provide tenant-specific statistics and resource listings.

Method	Endpoint	Description	Auth
GET	`/api/v1/Tenants/tree`	Get the full tenant hierarchy tree from the current admin's scope.	🔒 Required
GET	`/api/v1/Tenants/myChildren`	List the current admin's tenant's direct children.	🔒 Required
GET	`/api/v1/Tenants/myTenantAndChildren`	Retrieve current tenant and all immediate sub-tenants with organizational hierarchy status.	🔒 Required
GET	`/api/v1/Tenants/{id}/children`	List direct children of a specific tenant.	🔒 Required
GET	`/api/v1/Tenants/{id}/stats`	Get statistics for a tenant (admin count, user count, storage usage).	🔒 Required
GET	`/api/v1/Tenants/{id}/descendant-count`	Get total aggregate count of all descendant tenant workspaces across the sub-tree.	🔒 Required

GET /api/v1/Tenants/tree — Tree ResponseJSON

[
  {
    "id": "root-uuid",
    "name": "Headquarters",
    "code": "HQ",
    "level": 0,
    "children": [
      {
        "id": "branch-1-uuid",
        "name": "East Branch",
        "code": "EAST",
        "level": 1,
        "children": [
          {
            "id": "sub-branch-uuid",
            "name": "East Sub-Office",
            "code": "EAST_SUB",
            "level": 2,
            "children": []
          }
        ]
      }
    ]
  }
]

Admin Management Endpoints

Method	Endpoint	Description	Auth
GET	`/api/v1/Tenants/{id}/admins`	List all admins belonging to a specific tenant.	🔒 Required
GET	`/api/v1/Tenants/{id}/roles`	List all roles belonging to a specific tenant.	🔒 Required

Role & Permission Endpoints

Method	Endpoint	Description	Auth
GET	`/api/v1/Tenants/creation-permissions`	Check administrative entitlements to create child tenants and allocate quotas.	🔒 Required
GET	`/api/v1/Tenants/{id}/permissions`	List all permissions available in a specific tenant's scope.	🔒 Required
GET	`/api/v1/Tenants/{id}/permissions/grouped`	Retrieve all permissions grouped by functional module for role assignment.	🔒 Required
PUT	`/api/v1/Tenants/{id}/permissions`	Update permission delegations and granted feature policies for the tenant.	🔒 Required

Tenant Settings

Method	Endpoint	Description	Auth
GET	`/api/v1/Tenants/{id}/settings`	Get the full settings object for a tenant.	🔒 Required
PUT	`/api/v1/Tenants/{id}/settings`	Update tenant settings (registration policy, language, limits, password policy).	🔒 Required
POST	`/api/v1/Tenants/{id}/logo`	Upload a tenant logo (max 5 MB, jpg/png/svg/webp).	🔒 Required

GET /api/v1/Tenants/{id}/settings — ResponseJSON

{
  "maxAdmins": 50,
  "maxRoles": 100,
  "maxSubTenants": 10,
  "passwordMinLength": 8,
  "passwordRequireUppercase": true,
  "passwordRequireNumber": true,
  "passwordRequireSpecial": true,
  "passwordExpiryDays": 90,
  "loginLockoutThreshold": 5,
  "loginLockoutMinutes": 15,
  "require2FA": false,
  "auditRetentionDays": 90,
  "auditEnabled": true,
  "logoUrl": "/uploads/tenants/acme-logo.png",
  "faviconUrl": "/uploads/tenants/favicon.ico",
  "primaryColor": "#1E40AF",
  "secondaryColor": "#1D4ED8",
  "companyName": "Acme Corporation",
  "loginHeadline": "Welcome to Acme Corp",
  "loginSubtitle": "Access the secure admin panel",
  "identityProviderMode": "Single",
  "loginBrandingJson": "{}",
  "dashboardThemeJson": "{}",
  "termsOfServiceUrl": "https://scripe.com/tos",
  "privacyPolicyUrl": "https://scripe.com/privacy"
}

Base Configuration

Method	Endpoint	Description	Auth
GET	`/api/v1/Tenants/{id}/domains`	List all custom hostnames and verification tokens registered for the tenant.	🔒 Required
POST	`/api/v1/Tenants/{id}/domains`	Register a new custom domain for white-label routing with DNS challenge token.	🔒 Required
DELETE	`/api/v1/Tenants/{id}/domains/{domainId}`	Delete a custom domain mapping from the tenant routing configuration.	🔒 Required
PUT	`/api/v1/Tenants/{id}/domains/{domainId}/primary`	Designate a verified domain as the canonical host for tenant communications.	🔒 Required
POST	`/api/v1/Tenants/{id}/domains/{domainId}/verify`	Trigger an asynchronous DNS TXT/CNAME validation check for domain ownership.	🔒 Required

GET /api/v1/Tenants/{id}/domains — ResponseJSON

{
  "tenantId": "tenant-uuid-f8e7d6c5",
  "domains": [
    {
      "id": "domain-uuid-1",
      "domainName": "acme.myplatform.com",
      "isPrimary": true,
      "isCustom": false,
      "isVerified": true
    },
    {
      "id": "domain-uuid-2",
      "domainName": "custom.acme.com",
      "isPrimary": false,
      "isCustom": true,
      "isVerified": false,
      "verificationToken": "scripe-verification-token-xyz123...",
      "dnsRecordType": "TXT",
      "dnsRecordValue": "scripe-verification-token-xyz123..."
    }
  ]
}

PreviousAdmin Management API NextRole & Permission API