Tenant Management¶

Section: MSP Multi-Tenancy | Article 38
Audience: MSP Administrators
Last Updated: 2026-04-07

Overview¶

Once tenants are provisioned, MSP administrators can manage their lifecycle: list tenants, view details, suspend and reinstate tenants, and deprovision tenants that are no longer needed. All operations are available through the web portal and the REST API.

List Tenants¶

Retrieve all tenants in your MSP deployment.

PowerShell¶

$tenants = Invoke-RestMethod -Uri "https://rppam.corp.local:7101/api/v1/msp/tenants" `
    -Headers @{ Authorization = "Bearer $mspAdminJwt" }

$tenants | Format-Table shortCode, displayName, status, createdUtc

curl¶

curl -s "https://rppam.corp.local:7101/api/v1/msp/tenants" \
  -H "Authorization: Bearer $MSP_ADMIN_JWT" | jq '.[] | {shortCode, displayName, status, createdUtc}'

Example output:

shortCode	displayName	status	createdUtc
acme-corp	Acme Corporation	active	2026-04-07T14:30:00Z
contoso	Contoso Ltd	active	2026-03-15T09:00:00Z
fabrikam	Fabrikam Inc	suspended	2026-02-01T11:00:00Z

Filtering and Pagination¶

# Filter by status
Invoke-RestMethod -Uri "https://rppam.corp.local:7101/api/v1/msp/tenants?status=active" `
    -Headers @{ Authorization = "Bearer $mspAdminJwt" }

# Paginate (page size 25, page 2)
Invoke-RestMethod -Uri "https://rppam.corp.local:7101/api/v1/msp/tenants?pageSize=25&page=2" `
    -Headers @{ Authorization = "Bearer $mspAdminJwt" }

# Filter by status
curl -s "https://rppam.corp.local:7101/api/v1/msp/tenants?status=active" \
  -H "Authorization: Bearer $MSP_ADMIN_JWT" | jq .

# Paginate
curl -s "https://rppam.corp.local:7101/api/v1/msp/tenants?pageSize=25&page=2" \
  -H "Authorization: Bearer $MSP_ADMIN_JWT" | jq .

Get Tenant Detail¶

Retrieve detailed information about a specific tenant.

PowerShell¶

$tenantId = "f47ac10b-58cc-4372-a567-0e02b2c3d479"
$detail = Invoke-RestMethod `
    -Uri "https://rppam.corp.local:7101/api/v1/msp/tenants/$tenantId" `
    -Headers @{ Authorization = "Bearer $mspAdminJwt" }

$detail | ConvertTo-Json -Depth 3

curl¶

TENANT_ID="f47ac10b-58cc-4372-a567-0e02b2c3d479"
curl -s "https://rppam.corp.local:7101/api/v1/msp/tenants/$TENANT_ID" \
  -H "Authorization: Bearer $MSP_ADMIN_JWT" | jq .

Example response:

{
  "tenantId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "shortCode": "acme-corp",
  "displayName": "Acme Corporation",
  "contactEmail": "it@acmecorp.com",
  "status": "active",
  "createdUtc": "2026-04-07T14:30:00Z",
  "maxUsers": 500,
  "maxResources": 200,
  "currentUsers": 47,
  "currentResources": 83,
  "enabledModules": ["ad", "ssh"],
  "databaseName": "rppam_tenant_acme_corp",
  "lastActivityUtc": "2026-04-07T16:45:00Z"
}

Note: MSP admins can see tenant metadata (user counts, resource counts, module list) but cannot see individual users, vault entries, or detailed audit data.

Suspend a Tenant¶

Suspending a tenant disables all access for that tenant's users while preserving their data.

What Happens When a Tenant Is Suspended¶

Component	Effect
User logins	All logins rejected with "tenant suspended" error
Active sessions	Existing sessions are invalidated immediately
Active grants	All active grants are revoked (keys removed, temp users dropped)
Scheduled tasks	Paused (grant expirations, background jobs)
Data	Fully preserved — database, vault, audit logs remain intact
Modules	Disconnected (no outbound connections to AD, SSH, etc.)
Billing	`tenant.suspended` event recorded

PowerShell¶

$tenantId = "f47ac10b-58cc-4372-a567-0e02b2c3d479"
Invoke-RestMethod `
    -Uri "https://rppam.corp.local:7101/api/v1/msp/tenants/$tenantId/suspend" `
    -Method POST `
    -Headers @{ Authorization = "Bearer $mspAdminJwt" }

curl¶

TENANT_ID="f47ac10b-58cc-4372-a567-0e02b2c3d479"
curl -s -X POST "https://rppam.corp.local:7101/api/v1/msp/tenants/$TENANT_ID/suspend" \
  -H "Authorization: Bearer $MSP_ADMIN_JWT" | jq .

Reinstate a Tenant¶

Reinstating restores a suspended tenant to active status.

What Happens When a Tenant Is Reinstated¶

Component	Effect
User logins	Enabled — users can log in again
Data	Unchanged — all data preserved from before suspension
Modules	Reconnected and health-checked
Grants	Previously active grants are not restored (they were revoked on suspension)
Billing	`tenant.reinstated` event recorded

PowerShell¶

$tenantId = "f47ac10b-58cc-4372-a567-0e02b2c3d479"
Invoke-RestMethod `
    -Uri "https://rppam.corp.local:7101/api/v1/msp/tenants/$tenantId/reinstate" `
    -Method POST `
    -Headers @{ Authorization = "Bearer $mspAdminJwt" }

curl¶

TENANT_ID="f47ac10b-58cc-4372-a567-0e02b2c3d479"
curl -s -X POST "https://rppam.corp.local:7101/api/v1/msp/tenants/$TENANT_ID/reinstate" \
  -H "Authorization: Bearer $MSP_ADMIN_JWT" | jq .

Deprovision a Tenant¶

Deprovisioning marks a tenant for deletion. This is a destructive operation with a safety retention period.

What Happens When a Tenant Is Deprovisioned¶

Phase	Timing	What Happens
Immediate	Day 0	Tenant is suspended (all access revoked); status changes to `deprovisioning`
Retention period	Days 1-30	Data is preserved but inaccessible; tenant can be restored by contacting support
Permanent deletion	Day 31	Database dropped, encryption keys destroyed, all data permanently deleted

PowerShell¶

$tenantId = "f47ac10b-58cc-4372-a567-0e02b2c3d479"
Invoke-RestMethod `
    -Uri "https://rppam.corp.local:7101/api/v1/msp/tenants/$tenantId/deprovision" `
    -Method POST `
    -Headers @{ Authorization = "Bearer $mspAdminJwt" } `
    -ContentType "application/json" `
    -Body '{"confirmShortCode": "acme-corp"}'

curl¶

TENANT_ID="f47ac10b-58cc-4372-a567-0e02b2c3d479"
curl -s -X POST "https://rppam.corp.local:7101/api/v1/msp/tenants/$TENANT_ID/deprovision" \
  -H "Authorization: Bearer $MSP_ADMIN_JWT" \
  -H "Content-Type: application/json" \
  -d '{"confirmShortCode": "acme-corp"}' | jq .

Safety check: You must provide confirmShortCode matching the tenant's short code. This prevents accidental deprovisioning.

Warning: After the 30-day retention period, data deletion is permanent and irreversible. Ensure you have exported any needed data before deprovisioning.

Billing Events¶

RP-PAM records billing events for each tenant lifecycle change. These events can be exported for invoicing and reporting.

Event	Trigger	Data Included
`tenant.provisioned`	New tenant created	Tenant ID, short code, timestamp
`tenant.suspended`	Tenant suspended	Tenant ID, reason, timestamp
`tenant.reinstated`	Tenant reinstated	Tenant ID, timestamp
`tenant.deprovisioned`	Tenant marked for deletion	Tenant ID, retention end date, timestamp
`tenant.deleted`	Retention period expired, data destroyed	Tenant ID, timestamp
`tenant.usage.monthly`	End of each calendar month	Tenant ID, user count, resource count, grant count

Retrieve Billing Events¶

PowerShell:

# All events for a tenant
$tenantId = "f47ac10b-58cc-4372-a567-0e02b2c3d479"
Invoke-RestMethod `
    -Uri "https://rppam.corp.local:7101/api/v1/msp/tenants/$tenantId/billing-events?from=2026-04-01&to=2026-04-30" `
    -Headers @{ Authorization = "Bearer $mspAdminJwt" }

# All events across all tenants
Invoke-RestMethod `
    -Uri "https://rppam.corp.local:7101/api/v1/msp/billing-events?from=2026-04-01&to=2026-04-30" `
    -Headers @{ Authorization = "Bearer $mspAdminJwt" }

curl:

# All events for a tenant
TENANT_ID="f47ac10b-58cc-4372-a567-0e02b2c3d479"
curl -s "https://rppam.corp.local:7101/api/v1/msp/tenants/$TENANT_ID/billing-events?from=2026-04-01&to=2026-04-30" \
  -H "Authorization: Bearer $MSP_ADMIN_JWT" | jq .

# All events across all tenants
curl -s "https://rppam.corp.local:7101/api/v1/msp/billing-events?from=2026-04-01&to=2026-04-30" \
  -H "Authorization: Bearer $MSP_ADMIN_JWT" | jq .

Troubleshooting¶

Problem	Cause	Solution
Cannot suspend tenant	Caller lacks `msp-admin` role	Verify JWT belongs to an MSP admin
Reinstate fails with "not suspended"	Tenant is active or deprovisioning	Check tenant status; deprovisioning tenants cannot be reinstated via API
Deprovision rejected	`confirmShortCode` does not match	Provide the exact short code of the tenant
Billing events missing	Event not yet generated	Monthly usage events are generated at month-end
Tenant shows "unhealthy" after reinstate	Module connections need time to reconnect	Wait 60 seconds and re-check; verify target systems are reachable

Next Steps¶

Tenant Provisioning — Create new tenants
MSP Overview — Understand the multi-tenancy architecture
Backup and Restore — Ensure tenant data is backed up