Use Case 016: Tenant Provisioning and Management

Overview

Description

This use case describes the tenant provisioning and lifecycle management system that enables Application Manager to orchestrate multi-tenant architectures across registered applications. When ApplicationUsers are created or applications are registered, the system automatically provisions isolated tenant environments by calling application-specific webhooks. The system manages the complete tenant lifecycle including activation, suspension, deactivation, data retention, and deprovisioning. Unlike Riptide Auth's trial-focused approach, this supports permanent production tenants with subscription billing, enterprise configurations, and long-term data retention policies.

Actors

Preconditions

1. Application Manager platform is running
2. At least one application is registered with provisioning endpoints configured
3. AdminUser has tenant:manage capability
4. Database schema for tenant entities is initialized
5. Application webhooks are accessible and authenticated

Postconditions

Success Postconditions

1. Tenant record created/updated in Application Manager database
2. Tenant provisioned in target application(s) via webhook callbacks
3. Tenant ID assigned to ApplicationUser(s)
4. Tenant context available for session validation
5. Provisioning status logged in audit trail
6. Billing system notified of tenant lifecycle events (if integrated)

Failure Postconditions

1. Tenant provisioning rolled back if webhook calls fail
2. ApplicationUser creation blocked if provisioning fails (configurable)
3. Error logged with detailed failure reason
4. Alert sent to AdminUser for manual intervention
5. Retry scheduled for transient failures

Triggers

• AdminUser provisions ApplicationUser (UC-015) triggering tenant creation
• AdminUser explicitly creates tenant for organization
• Application registration triggers admin tenant creation
• AdminUser suspends/reactivates tenant
• AdminUser initiates tenant deprovisioning
• Subscription billing system requests tenant suspension (non-payment)
• Compliance policy triggers tenant data retention/deletion

Basic Flow (Happy Path)

sequenceDiagram
    actor Admin as AdminUser
    participant Web as Admin Web UI
    participant API as Application Manager API
    participant TenantSvc as Tenant Service
    participant AppRegistry as Application Registry
    participant ExtApp as External Application
    participant DB as Identity Database
    participant Audit as Audit Service
    participant Billing as Billing System

    Note over Admin,Billing: Tenant Provisioning Flow
    
    Admin->>Web: Create ApplicationUser (UC-015)
    Web->>API: POST /api/v1/users (ApplicationUser)
    
    API->>TenantSvc: Provision tenant for user
    TenantSvc->>DB: Create Tenant record
    DB->>TenantSvc: Tenant created (ID: tenant-123)
    
    TenantSvc->>AppRegistry: Get registered applications
    AppRegistry->>TenantSvc: Application list with endpoints
    
    loop For each application
        TenantSvc->>ExtApp: POST /api/tenants/provision
        Note over TenantSvc,ExtApp: Headers: X-Api-Key
        Note over TenantSvc,ExtApp: Body: tenantId, metadata
        
        ExtApp->>ExtApp: Validate API key
        ExtApp->>ExtApp: Create isolated tenant
        ExtApp->>ExtApp: Initialize default data
        ExtApp->>TenantSvc: 200 OK (provisioned)
        
        TenantSvc->>DB: Update ApplicationTenantMapping
        DB->>TenantSvc: Mapping saved
    end
    
    TenantSvc->>DB: Link User to Tenant
    DB->>TenantSvc: User-Tenant linked
    
    TenantSvc->>Audit: Log provisioning success
    Audit->>Audit: Store audit record
    
    TenantSvc->>Billing: Notify tenant created
    Billing->>Billing: Create billing account
    
    TenantSvc->>API: Provisioning complete
    API->>Web: 201 Created (user + tenant)
    Web->>Admin: Success: User and tenant created
    
    Note over Admin,Billing: Tenant Suspension Flow
    
    Admin->>Web: Suspend tenant (non-payment)
    Web->>API: PATCH /api/v1/tenants/{id}/suspend
    
    API->>TenantSvc: Suspend tenant
    TenantSvc->>DB: Update Status = Suspended
    DB->>TenantSvc: Status updated
    
    loop For each application
        TenantSvc->>ExtApp: PATCH /api/tenants/{tenantId}/suspend
        ExtApp->>ExtApp: Disable tenant access
        ExtApp->>TenantSvc: 200 OK
    end
    
    TenantSvc->>Audit: Log suspension
    TenantSvc->>Billing: Notify tenant suspended
    
    TenantSvc->>API: Suspension complete
    API->>Web: 200 OK
    Web->>Admin: Tenant suspended successfully
    
    Note over Admin,Billing: Tenant Deprovisioning Flow
    
    Admin->>Web: Deprovision tenant
    Web->>API: DELETE /api/v1/tenants/{id}
    
    API->>TenantSvc: Confirm deprovisioning
    Note over API,TenantSvc: Confirmation required
    
    loop For each application
        TenantSvc->>ExtApp: DELETE /api/tenants/{tenantId}
        ExtApp->>ExtApp: Purge tenant data
        ExtApp->>ExtApp: Delete tenant record
        ExtApp->>TenantSvc: 204 No Content
        
        TenantSvc->>DB: Update mapping (status: deprovisioned)
    end
    
    TenantSvc->>DB: Mark Tenant as Deprovisioned
    Note over TenantSvc,DB: Retain metadata for compliance
    
    TenantSvc->>Audit: Log deprovisioning
    TenantSvc->>Billing: Notify tenant deprovisioned
    
    TenantSvc->>API: Deprovisioning complete
    API->>Web: 200 OK (summary)
    Web->>Admin: Show deprovisioning summary

Detailed Steps

1. Tenant Creation Triggered

   • ApplicationUser creation (UC-015) triggers tenant provisioning
   • OR AdminUser explicitly creates tenant for organization
   • OR Application registration creates admin tenant

2. System Generates Tenant Record

   • Create Tenant entity with unique GUID
   • Set Status = Provisioning
   • Assign OrganizationName, ContactEmail, PlanTier
   • Generate ApiKey for tenant-to-platform communication
   • Set CreatedBy to AdminUser ID
   • Set CreatedAt timestamp

3. System Retrieves Application List

   • Query all registered applications with ProvisioningUrl configured
   • Filter by applications user should have access to (based on plan/roles)
   • Order by priority (critical apps first)

4. System Calls Application Provisioning Webhooks

   • For each application in parallel (with configurable concurrency limit):
     • POST to {app.ProvisioningUrl}
     • Headers: X-Api-Key: {api-key}, X-Tenant-Id: {tenantId}
     • Body: Tenant metadata (ID, name, email, plan tier, max users)
     • Timeout: 30 seconds
     • Retry: 3 attempts with exponential backoff

5. Application Provisions Tenant

   • Validates API key from Application Manager
   • Creates isolated tenant database/schema
   • Initializes default application data
   • Creates admin user account linked to ApplicationUser
   • Returns success with optional application-specific tenant ID

6. System Records Provisioning Results

   • Create ApplicationTenantMapping for each successful provisioning
   • Store application-specific tenant ID if returned
   • Update Tenant.Status = Active when all apps succeed
   • Update Tenant.Status = PartiallyProvisioned if some fail
   • Log failures with error messages for retry

7. System Links User to Tenant

   • Update ApplicationUser.TenantId with new tenant ID
   • Create default tenant admin role assignment
   • Grant access to provisioned applications

8. System Notifies External Systems

   • Send event to audit service with full provisioning details
   • Notify billing system to create account
   • Send email to organization contact (optional)
   • Create support ticket for manual verification (if configured)

Alternative Flows

Alt Flow 1: Provisioning Webhook Failure

sequenceDiagram
    participant TenantSvc as Tenant Service
    participant ExtApp as External Application
    participant DB as Identity Database
    participant Retry as Retry Queue
    participant Alert as Alert Service

    TenantSvc->>ExtApp: POST /api/tenants/provision
    
    alt Application Timeout
        ExtApp--xTenantSvc: [Timeout after 30s]
        TenantSvc->>Retry: Schedule retry (attempt 1/3)
        TenantSvc->>DB: Update Status = ProvisioningRetrying
    else Application Error 500
        ExtApp-->>TenantSvc: 500 Internal Server Error
        TenantSvc->>Retry: Schedule retry (attempt 1/3)
    else Application Invalid Response
        ExtApp-->>TenantSvc: 200 OK (malformed JSON)
        TenantSvc->>DB: Log invalid response
        TenantSvc->>Retry: Schedule retry (attempt 1/3)
    end
    
    Note over Retry: Wait 10 seconds (exponential)
    
    Retry->>TenantSvc: Execute retry attempt 2
    TenantSvc->>ExtApp: POST /api/tenants/provision
    ExtApp--xTenantSvc: [Still failing]
    
    TenantSvc->>Retry: Schedule retry (attempt 2/3)
    Note over Retry: Wait 30 seconds
    
    Retry->>TenantSvc: Execute retry attempt 3
    TenantSvc->>ExtApp: POST /api/tenants/provision
    ExtApp--xTenantSvc: [Final failure]
    
    TenantSvc->>DB: Update Status = ProvisioningFailed
    TenantSvc->>DB: Store error details
    TenantSvc->>Alert: Send alert to AdminUser
    
    Note over TenantSvc: Admin must manually intervene

Steps:

1. Application webhook call fails (timeout, 5xx error, network issue)
2. System immediately retries (attempt 1 of 3) after 10 seconds
3. If still failing, wait 30 seconds and retry (attempt 2)
4. If still failing, wait 90 seconds and final retry (attempt 3)
5. After 3 failures, mark ApplicationTenantMapping.Status = Failed
6. Update Tenant.Status = PartiallyProvisioned (if other apps succeeded)
7. Create alert for AdminUser with error details
8. AdminUser can manually retry via UI: "Retry Failed Provisioning"
9. AdminUser can exclude failing application and mark tenant as Active

Alt Flow 2: Multi-Application Partial Provisioning

sequenceDiagram
    participant TenantSvc as Tenant Service
    participant App1 as App 1 (Success)
    participant App2 as App 2 (Failed)
    participant App3 as App 3 (Success)
    participant DB as Database

    par Parallel Provisioning
        TenantSvc->>App1: POST /api/tenants/provision
        App1->>TenantSvc: 200 OK (success)
        
        TenantSvc->>App2: POST /api/tenants/provision
        App2--xTenantSvc: 500 Error (failed)
        
        TenantSvc->>App3: POST /api/tenants/provision
        App3->>TenantSvc: 200 OK (success)
    end
    
    TenantSvc->>DB: Save results
    Note over TenantSvc,DB: App1: Provisioned<br/>App2: Failed<br/>App3: Provisioned
    
    TenantSvc->>DB: Update Tenant.Status = PartiallyProvisioned
    
    Note over TenantSvc: Admin sees mixed status<br/>Can retry App2 or proceed

Steps:

1. System provisions tenant across 3 applications
2. App1 succeeds, App2 fails, App3 succeeds
3. Tenant.Status = PartiallyProvisioned
4. AdminUser sees status: "2 of 3 applications provisioned"
5. AdminUser options:
   • Retry failed application
   • Mark tenant as Active (accept partial provisioning)
   • Deprovision successful apps and abort
6. User can still access successfully provisioned applications

Alt Flow 3: Tenant Suspension (Non-Payment)

Steps:

1. Billing system detects failed payment
2. Billing system calls: PATCH /api/v1/tenants/{id}/suspend
3. System validates billing system API key
4. System updates Tenant.Status = Suspended
5. System calls suspension webhook for each application:
   • PATCH /api/tenants/{tenantId}/suspend
6. Applications disable access but retain data
7. Users attempting to access see "Account Suspended" message
8. AdminUser can view suspension reason: "Payment Failed - Renew by "
9. After grace period (default 30 days), tenant moves to deprovisioning

Alt Flow 4: Tenant Reactivation

Steps:

1. Billing system confirms payment received
2. Billing system calls: PATCH /api/v1/tenants/{id}/reactivate
3. System validates tenant was suspended (not deprovisioned)
4. System updates Tenant.Status = Active
5. System calls reactivation webhook for each application:
   • PATCH /api/tenants/{tenantId}/reactivate
6. Applications re-enable access
7. System sends welcome back email to organization
8. Audit log records reactivation with reason

Alt Flow 5: Tenant Data Retention (Compliance)

Steps:

1. AdminUser initiates soft delete: "Deprovision but retain for 90 days"
2. System updates Tenant.Status = Deprovisioned
3. System sets Tenant.DataRetentionUntil = Now + 90 days
4. System calls application deprovisioning webhooks
5. Applications archive tenant data (move to cold storage)
6. Users cannot access applications
7. After 90 days, scheduled job calls hard delete:
   • Applications permanently purge tenant data
   • Application Manager removes ApplicationTenantMapping records
   • Tenant metadata retained indefinitely for audit

Alt Flow 6: Tenant Migration (Environment Transfer)

Steps:

1. AdminUser requests tenant migration: Dev → Staging → Production
2. System validates target environment is registered
3. System exports tenant metadata and configuration
4. System provisions tenant in target environment (normal flow)
5. Applications handle data migration (out of scope for Application Manager)
6. System updates tenant's environment identifier
7. Users receive notification of migration
8. Old environment tenant marked for deprovisioning (with grace period)

Business Rules

Data Requirements

Tenant Entity

{
  "Id": "uuid-v4 (primary key)",
  "OrganizationName": "string (required, 1-200 chars)",
  "OrganizationDomain": "string (nullable, validated domain format)",
  "ContactEmail": "string (required, validated email)",
  "ContactName": "string (required, 1-200 chars)",
  "ContactPhone": "string (nullable, 20 chars)",
  "PlanTier": "enum (Free, Starter, Professional, Enterprise)",
  "MaxUsers": "int (nullable, based on plan tier)",
  "MaxApplications": "int (nullable, based on plan tier)",
  "ApiKey": "string (32 bytes hex, unique)",
  "Status": "enum (Provisioning, Active, PartiallyProvisioned, Suspended, Deprovisioned)",
  "StatusReason": "string (nullable, reason for current status)",
  "IsAdminTenant": "bool (default: false, true for Riptide team)",
  "Environment": "enum (Development, Staging, Production)",
  "DataRetentionUntil": "datetime (nullable, soft delete expiration)",
  "CreatedBy": "uuid-v4 (AdminUser ID)",
  "CreatedAt": "datetime (UTC)",
  "UpdatedAt": "datetime (UTC)",
  "LastAccessedAt": "datetime (nullable, UTC)",
  "SuspendedAt": "datetime (nullable, UTC)",
  "DeprovisionedAt": "datetime (nullable, UTC)",
  "Metadata": "json (extensible key-value store)"
}

Status Enum:

• Provisioning - Initial state, webhook calls in progress
• Active - All applications provisioned successfully
• PartiallyProvisioned - Some applications failed, manual intervention needed
• Suspended - Access disabled but data retained (payment issue, policy violation)
• Deprovisioned - Tenant removed, data retention policy active

PlanTier Enum:

• Free - Trial/demo tier (limited features, 30-day expiration)
• Starter - Small business tier (5 users, core features)
• Professional - Mid-market tier (25 users, advanced features)
• Enterprise - Enterprise tier (unlimited users, custom SLA)

ApplicationTenantMapping Entity

{
  "Id": "uuid-v4 (primary key)",
  "TenantId": "uuid-v4 (foreign key to Tenant)",
  "ApplicationId": "uuid-v4 (foreign key to Application)",
  "ApplicationSpecificTenantId": "string (nullable, app's internal tenant ID)",
  "Status": "enum (Provisioning, Provisioned, Failed, Suspended, Deprovisioned)",
  "ProvisioningAttempts": "int (default: 0, max: 3)",
  "LastProvisioningAttempt": "datetime (nullable, UTC)",
  "LastProvisioningError": "string (nullable, error message)",
  "ProvisionedAt": "datetime (nullable, UTC)",
  "ProvisionedBy": "uuid-v4 (AdminUser ID)",
  "SuspendedAt": "datetime (nullable, UTC)",
  "DeprovisionedAt": "datetime (nullable, UTC)",
  "Metadata": "json (app-specific provisioning data)"
}

TenantUser Entity (Join Table)

{
  "Id": "uuid-v4 (primary key)",
  "TenantId": "uuid-v4 (foreign key)",
  "UserId": "uuid-v4 (foreign key to ApplicationUser)",
  "Role": "string (tenant-admin, tenant-member, tenant-billing)",
  "JoinedAt": "datetime (UTC)",
  "InvitedBy": "uuid-v4 (nullable, inviting user ID)",
  "IsActive": "bool (default: true)"
}

TenantProvisioningLog Entity

{
  "Id": "uuid-v4 (primary key)",
  "TenantId": "uuid-v4 (foreign key)",
  "ApplicationId": "uuid-v4 (nullable, null for tenant-level events)",
  "EventType": "enum (ProvisioningStarted, ProvisioningSucceeded, ProvisioningFailed, Suspended, Reactivated, Deprovisioned)",
  "Status": "enum (Success, Failed, Retrying)",
  "Message": "string (event description)",
  "ErrorDetails": "string (nullable, stack trace or error message)",
  "Attempt": "int (retry attempt number)",
  "RequestPayload": "json (webhook request body)",
  "ResponsePayload": "json (nullable, webhook response)",
  "HttpStatusCode": "int (nullable, webhook response code)",
  "Duration": "int (milliseconds)",
  "Timestamp": "datetime (UTC)",
  "PerformedBy": "uuid-v4 (nullable, AdminUser ID)"
}

API Endpoints

Tenant Management

Create Tenant

Endpoint: POST /api/v1/tenants

Authentication: Required (tenant:create capability)

Request Body:

{
  "organizationName": "Acme Corporation",
  "organizationDomain": "acme.com",
  "contactEmail": "admin@acme.com",
  "contactName": "Jane Doe",
  "contactPhone": "+1-555-123-4567",
  "planTier": "Professional",
  "maxUsers": 25,
  "environment": "Production",
  "applicationIds": [
    "app-1-guid",
    "app-2-guid"
  ],
  "metadata": {
    "industry": "Technology",
    "companySize": "51-200",
    "referralSource": "Partner"
  }
}

Success Response: 201 Created

{
  "tenantId": "tenant-123",
  "organizationName": "Acme Corporation",
  "status": "Provisioning",
  "apiKey": "32-byte-hex-string",
  "provisioningStatus": {
    "totalApplications": 2,
    "provisioned": 0,
    "failed": 0,
    "inProgress": 2
  },
  "applications": [
    {
      "applicationId": "app-1-guid",
      "applicationName": "value-manager",
      "status": "Provisioning"
    },
    {
      "applicationId": "app-2-guid",
      "applicationName": "fee-manager",
      "status": "Provisioning"
    }
  ],
  "createdAt": "2026-02-02T10:30:00Z",
  "createdBy": "admin-user-id"
}

Get Tenant Details

Endpoint: GET /api/v1/tenants/{tenantId}

Authentication: Required (tenant:read capability)

Success Response: 200 OK

{
  "tenantId": "tenant-123",
  "organizationName": "Acme Corporation",
  "organizationDomain": "acme.com",
  "contactEmail": "admin@acme.com",
  "contactName": "Jane Doe",
  "planTier": "Professional",
  "maxUsers": 25,
  "currentUsers": 12,
  "status": "Active",
  "statusReason": null,
  "environment": "Production",
  "isAdminTenant": false,
  "applications": [
    {
      "applicationId": "app-1-guid",
      "applicationName": "value-manager",
      "displayName": "Value Manager",
      "status": "Provisioned",
      "provisionedAt": "2026-02-02T10:30:45Z",
      "applicationTenantId": "vm-tenant-456"
    }
  ],
  "users": [
    {
      "userId": "user-789",
      "fullName": "Jane Doe",
      "email": "jane@acme.com",
      "role": "tenant-admin",
      "joinedAt": "2026-02-02T10:30:00Z"
    }
  ],
  "createdAt": "2026-02-02T10:30:00Z",
  "lastAccessedAt": "2026-02-02T14:22:00Z",
  "metadata": {
    "industry": "Technology",
    "companySize": "51-200"
  }
}

List All Tenants

Endpoint: GET /api/v1/tenants

Authentication: Required (tenant:list capability)

Query Parameters:

• status - Filter by status (Active, Suspended, etc.)
• planTier - Filter by plan tier
• environment - Filter by environment
• search - Search by organization name or contact email
• page - Page number (default: 1)
• pageSize - Items per page (default: 50, max: 200)
• sortBy - Sort field (createdAt, organizationName, lastAccessedAt)
• sortOrder - Sort direction (asc, desc)

Success Response: 200 OK

{
  "tenants": [
    {
      "tenantId": "tenant-123",
      "organizationName": "Acme Corporation",
      "contactEmail": "admin@acme.com",
      "planTier": "Professional",
      "status": "Active",
      "userCount": 12,
      "applicationCount": 3,
      "createdAt": "2026-02-02T10:30:00Z",
      "lastAccessedAt": "2026-02-02T14:22:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "pageSize": 50,
    "totalItems": 145,
    "totalPages": 3
  }
}

Update Tenant

Endpoint: PATCH /api/v1/tenants/{tenantId}

Authentication: Required (tenant:update capability)

Request Body:

{
  "organizationName": "Acme Corp (Updated)",
  "contactEmail": "newadmin@acme.com",
  "planTier": "Enterprise",
  "maxUsers": 100,
  "metadata": {
    "billingContact": "billing@acme.com"
  }
}

Success Response: 200 OK (updated tenant object)

Suspend Tenant

Endpoint: PATCH /api/v1/tenants/{tenantId}/suspend

Authentication: Required (tenant:suspend capability)

Request Body:

{
  "reason": "Payment failed - account overdue",
  "gracePeriodDays": 30,
  "notifyUsers": true
}

Success Response: 200 OK

{
  "tenantId": "tenant-123",
  "status": "Suspended",
  "statusReason": "Payment failed - account overdue",
  "suspendedAt": "2026-02-02T15:00:00Z",
  "gracePeriodEnds": "2026-03-04T15:00:00Z",
  "applicationsSuspended": 3,
  "usersNotified": 12
}

Reactivate Tenant

Endpoint: PATCH /api/v1/tenants/{tenantId}/reactivate

Authentication: Required (tenant:reactivate capability)

Success Response: 200 OK

{
  "tenantId": "tenant-123",
  "status": "Active",
  "reactivatedAt": "2026-02-02T16:00:00Z",
  "applicationsReactivated": 3
}

Retry Failed Provisioning

Endpoint: POST /api/v1/tenants/{tenantId}/retry-provisioning

Authentication: Required (tenant:provision capability)

Request Body:

{
  "applicationIds": [
    "app-2-guid"
  ]
}

Success Response: 200 OK

{
  "tenantId": "tenant-123",
  "retriedApplications": 1,
  "results": [
    {
      "applicationId": "app-2-guid",
      "status": "Provisioned",
      "message": "Successfully provisioned on retry"
    }
  ]
}

Deprovision Tenant

Endpoint: DELETE /api/v1/tenants/{tenantId}

Authentication: Required (tenant:delete capability)

Query Parameters:

• dataRetentionDays - Days to retain data (default: 90, max: 365)
• confirm - Must be "true" to confirm deletion

Request Body:

{
  "reason": "Customer requested account deletion",
  "notifyUsers": true
}

Success Response: 200 OK

{
  "tenantId": "tenant-123",
  "status": "Deprovisioned",
  "deprovisionedAt": "2026-02-02T17:00:00Z",
  "dataRetentionUntil": "2026-05-03T17:00:00Z",
  "applicationsDeprovisioned": 3,
  "usersNotified": 12,
  "summary": {
    "totalApplications": 3,
    "successfullyDeprovisioned": 3,
    "failed": 0
  }
}

Application-Specific Provisioning Webhooks

These endpoints are implemented by registered applications, not Application Manager.

Provision Tenant Webhook (Application Implements)

Endpoint: POST {app.ProvisioningUrl}

Example: POST https://value-manager.acme.com/api/tenants/provision

Headers:

X-Api-Key: {api-key-from-app-registration}
X-Tenant-Id: {tenant-id-from-application-manager}
Content-Type: application/json

Request Body (sent by Application Manager):

{
  "tenantId": "tenant-123",
  "organizationName": "Acme Corporation",
  "contactEmail": "admin@acme.com",
  "contactName": "Jane Doe",
  "planTier": "Professional",
  "maxUsers": 25,
  "environment": "Production",
  "metadata": {
    "industry": "Technology"
  }
}

Expected Response: 200 OK or 201 Created

{
  "success": true,
  "tenantId": "tenant-123",
  "applicationTenantId": "vm-tenant-456",
  "message": "Tenant provisioned successfully",
  "metadata": {
    "databaseSchema": "tenant_123",
    "storageQuota": "100GB"
  }
}

Error Response: 500 Internal Server Error

{
  "success": false,
  "error": "DatabaseConnectionFailed",
  "message": "Unable to create tenant database",
  "retryable": true
}

Suspend Tenant Webhook (Application Implements)

Endpoint: PATCH {app.ProvisioningUrl}/{tenantId}/suspend

Headers: Same as provisioning

Expected Response: 200 OK

{
  "success": true,
  "tenantId": "tenant-123",
  "message": "Tenant access disabled"
}

Reactivate Tenant Webhook (Application Implements)

Endpoint: PATCH {app.ProvisioningUrl}/{tenantId}/reactivate

Headers: Same as provisioning

Expected Response: 200 OK

Deprovision Tenant Webhook (Application Implements)

Endpoint: DELETE {app.ProvisioningUrl}/{tenantId}

Headers: Same as provisioning

Query Parameters:

• retainData - Boolean (if true, move to cold storage; if false, hard delete)

Expected Response: 204 No Content or 200 OK

{
  "success": true,
  "tenantId": "tenant-123",
  "message": "Tenant data purged successfully",
  "metadata": {
    "recordsDeleted": 15000,
    "storageFreed": "2.5GB"
  }
}

User Interface Mockups

Tenant List View

┌────────────────────────────────────────────────────────────────────────┐
│  Application Manager - Tenant Management                              │
│  ═══════════════════════════════════════════════════════════════════  │
│                                                                        │
│  [+ Create Tenant]                       Search: [___________] 🔍     │
│                                                                        │
│  Filters:                                                              │
│  Status: [All ▾]  Plan: [All ▾]  Environment: [Production ▾]         │
│                                                                        │
│  ┌──────────────────────────────────────────────────────────────────┐│
│  │ Organization      │ Contact      │ Plan   │ Status │ Users │ Apps││
│  ├──────────────────────────────────────────────────────────────────┤│
│  │ Acme Corporation  │ admin@acme   │ Pro    │ 🟢 Active │ 12/25│ 3  ││
│  │ Created: 2026-02-01 │ Last Access: 2 hours ago           [···] ││
│  │                                                                  ││
│  │ Beta Industries   │ beta@beta    │ Start  │ 🟡 Partial│  5/10│ 2  ││
│  │ Created: 2026-01-28 │ Last Access: 3 days ago            [···] ││
│  │                                                                  ││
│  │ Global Dynamics   │ ops@global   │ Ent    │ 🔴 Suspended│ 45  │ 5  ││
│  │ Created: 2025-12-15 │ Suspended: Payment overdue         [···] ││
│  │                                                                  ││
│  │ Test Company      │ test@test    │ Free   │ ⚫ Deprov  │  0   │ 1  ││
│  │ Created: 2025-11-20 │ Deprovisioned: 2026-01-30          [···] ││
│  └──────────────────────────────────────────────────────────────────┘│
│                                                                        │
│  Showing 1-4 of 145 tenants         [← Previous]  [1] 2 3 [Next →]  │
└────────────────────────────────────────────────────────────────────────┘

Tenant Details View

┌────────────────────────────────────────────────────────────────────────┐
│  ← Back to Tenants                                                     │
│                                                                        │
│  Acme Corporation                            [Edit] [Suspend] [Delete]│
│  ═══════════════════════════════════════════════════════════════════  │
│                                                                        │
│  Status: 🟢 Active                          Plan: Professional         │
│  Tenant ID: tenant-123                      Environment: Production    │
│  API Key: ****-****-****-ab12 [Show] [Regenerate]                     │
│                                                                        │
│  ┌─────────────────────────────────────────────────────────────────┐ │
│  │ Organization Details                                            │ │
│  │ ═══════════════════════════════════════════════════════════════ │ │
│  │ Organization Name: Acme Corporation                             │ │
│  │ Domain: acme.com                                                │ │
│  │ Contact: Jane Doe (admin@acme.com)                              │ │
│  │ Phone: +1-555-123-4567                                          │ │
│  │ Created: 2026-02-01 at 10:30 AM by Admin User                  │ │
│  │ Last Accessed: 2 hours ago                                      │ │
│  └─────────────────────────────────────────────────────────────────┘ │
│                                                                        │
│  ┌─────────────────────────────────────────────────────────────────┐ │
│  │ Applications (3)                                    [+ Add App] │ │
│  │ ═══════════════════════════════════════════════════════════════ │ │
│  │                                                                 │ │
│  │ 🟢 Value Manager                            Status: Provisioned │ │
│  │    Provisioned: 2026-02-01 at 10:32 AM                         │ │
│  │    App Tenant ID: vm-tenant-456                                │ │
│  │    [Launch] [Suspend] [Deprovision]                            │ │
│  │                                                                 │ │
│  │ 🟢 Fee Manager                              Status: Provisioned │ │
│  │    Provisioned: 2026-02-01 at 10:33 AM                         │ │
│  │    App Tenant ID: fm-tenant-789                                │ │
│  │    [Launch] [Suspend] [Deprovision]                            │ │
│  │                                                                 │ │
│  │ 🔴 Workflow Engine                          Status: Failed      │ │
│  │    Last Attempt: 2026-02-01 at 10:35 AM (3 attempts)           │ │
│  │    Error: Connection timeout                                   │ │
│  │    [Retry Provisioning] [View Logs]                            │ │
│  └─────────────────────────────────────────────────────────────────┘ │
│                                                                        │
│  ┌─────────────────────────────────────────────────────────────────┐ │
│  │ Users (12 / 25 max)                          [+ Invite User]   │ │
│  │ ═══════════════════════════════════════════════════════════════ │ │
│  │ Jane Doe (admin@acme.com)              Role: tenant-admin       │ │
│  │ John Smith (john@acme.com)             Role: tenant-member      │ │
│  │ [View All Users →]                                              │ │
│  └─────────────────────────────────────────────────────────────────┘ │
│                                                                        │
│  ┌─────────────────────────────────────────────────────────────────┐ │
│  │ Provisioning Logs                           [View All Logs →]  │ │
│  │ ═══════════════════════════════════════════════════════════════ │ │
│  │ 2026-02-01 10:35 AM │ Workflow Engine │ Failed (Attempt 3)     │ │
│  │ 2026-02-01 10:33 AM │ Fee Manager     │ Provisioned            │ │
│  │ 2026-02-01 10:32 AM │ Value Manager   │ Provisioned            │ │
│  │ 2026-02-01 10:30 AM │ Tenant Created  │ Success                │ │
│  └─────────────────────────────────────────────────────────────────┘ │
└────────────────────────────────────────────────────────────────────────┘

Create Tenant Dialog

┌──────────────────────────────────────────────────────────────┐
│  Create New Tenant                                           │
│  ══════════════════════════════════════════════════════════  │
│                                                              │
│  Organization Information                                    │
│                                                              │
│  Organization Name *                                         │
│  ┌────────────────────────────────────────────────────────┐ │
│  │ Acme Corporation                                       │ │
│  └────────────────────────────────────────────────────────┘ │
│                                                              │
│  Organization Domain                                         │
│  ┌────────────────────────────────────────────────────────┐ │
│  │ acme.com                                               │ │
│  └────────────────────────────────────────────────────────┘ │
│                                                              │
│  Contact Information                                         │
│                                                              │
│  Contact Name *              Contact Email *                │
│  ┌──────────────────────┐  ┌──────────────────────────────┐│
│  │ Jane Doe             │  │ admin@acme.com               ││
│  └──────────────────────┘  └──────────────────────────────┘│
│                                                              │
│  Contact Phone                                               │
│  ┌────────────────────────────────────────────────────────┐ │
│  │ +1-555-123-4567                                        │ │
│  └────────────────────────────────────────────────────────┘ │
│                                                              │
│  Plan & Configuration                                        │
│                                                              │
│  Plan Tier *                                                 │
│  ┌────────────────────────────────────────────────────────┐ │
│  │ Professional                                        ▾  │ │
│  └────────────────────────────────────────────────────────┘ │
│                                                              │
│  Max Users                   Environment                     │
│  ┌──────────────────────┐  ┌──────────────────────────────┐│
│  │ 25                   │  │ Production                ▾  ││
│  └──────────────────────┘  └──────────────────────────────┘│
│                                                              │
│  Applications to Provision *                                 │
│  ┌────────────────────────────────────────────────────────┐ │
│  │ ☑ Value Manager                                        │ │
│  │ ☑ Fee Manager                                          │ │
│  │ ☐ Workflow Engine                                      │ │
│  │ ☑ Configuration Manager                                │ │
│  └────────────────────────────────────────────────────────┘ │
│                                                              │
│  ℹ️ Selected applications will be provisioned automatically  │
│     with isolated tenant environments.                      │
│                                                              │
│  ─────────────────────────────────────────────────────────  │
│                                                              │
│                               [Cancel]  [Create Tenant]     │
└──────────────────────────────────────────────────────────────┘

Suspend Tenant Confirmation Dialog

┌──────────────────────────────────────────────────────────────┐
│  Suspend Tenant: Acme Corporation                            │
│  ══════════════════════════════════════════════════════════  │
│                                                              │
│  ⚠️ Warning: This will immediately disable access for all    │
│     users in this tenant across all applications.           │
│                                                              │
│  Affected:                                                   │
│  • 12 users                                                  │
│  • 3 applications (Value Manager, Fee Manager, Config Mgr)  │
│                                                              │
│  Reason for Suspension *                                     │
│  ┌────────────────────────────────────────────────────────┐ │
│  │ Payment failed - account overdue                       │ │
│  └────────────────────────────────────────────────────────┘ │
│                                                              │
│  Grace Period (days)                                         │
│  ┌────────────────────────────────────────────────────────┐ │
│  │ 30                                                     │ │
│  └────────────────────────────────────────────────────────┘ │
│  ℹ️ After grace period, tenant will be deprovisioned        │
│                                                              │
│  ☑ Send notification emails to all users                    │
│  ☑ Notify billing system                                    │
│                                                              │
│  ─────────────────────────────────────────────────────────  │
│                                                              │
│                          [Cancel]  [Suspend Tenant]         │
└──────────────────────────────────────────────────────────────┘

Security Considerations

Tenant Isolation

• Each tenant must have cryptographically unique API key (32 bytes)
• API keys transmitted only via HTTPS
• Applications enforce tenant-level data isolation
• No cross-tenant data access permitted
• Tenant context validated on every request

Webhook Security

• All provisioning webhooks require API key authentication
• Webhook URLs must be HTTPS only (no HTTP)
• Request signing with HMAC-SHA256 (optional enhancement)
• IP allowlisting for Application Manager webhook sources
• Rate limiting on webhook endpoints (10 requests/minute per tenant)

Deprovisioning Security

• Two-step confirmation required for deprovisioning
• AdminUser must have tenant:delete capability
• All deprovisioning actions logged in audit trail
• Data retention policies enforced (minimum 30 days for compliance)
• Cannot deprovision admin tenant

Access Control

• Tenant operations require specific capabilities (tenant:create, tenant:suspend, etc.)
• ApplicationUsers can only view/modify their own tenant
• AdminUsers can manage all tenants
• Billing system API key separate from admin user authentication

Audit & Compliance

• All tenant lifecycle events logged with actor, timestamp, reason
• Provisioning logs retained indefinitely
• Tenant metadata retained even after deprovisioning
• GDPR-compliant data deletion on request (with legal compliance check)

Non-Functional Requirements

Performance

• Tenant provisioning: < 60 seconds for 3 applications
• Webhook timeout: 30 seconds per application
• Parallel provisioning with max 5 concurrent webhook calls
• Tenant list query: < 500ms for 10,000 tenants
• Status updates propagate within 5 seconds

Reliability

• Webhook retry: 3 attempts with exponential backoff (10s, 30s, 90s)
• Failed provisioning does not block ApplicationUser creation (configurable)
• Partial provisioning allows tenant to be active with subset of applications
• Automatic recovery for transient network failures
• Dead letter queue for permanently failed webhooks

Scalability

• Support 10,000+ active tenants
• Handle 100 concurrent tenant provisioning requests
• Background job processes expired tenants (batch size: 100)
• Database indexes on: TenantId, Status, CreatedAt, OrganizationDomain

Observability

• Prometheus metrics: provisioning success rate, webhook latency, retry count
• Application Insights: tenant lifecycle events, application-specific provisioning times
• Alerts: provisioning failure rate > 10%, webhook timeout rate > 5%
• Dashboard: active tenants, provisioning queue depth, suspension rate

Disaster Recovery

• Tenant provisioning is idempotent (safe to retry)
• Webhook calls include correlation IDs for tracing
• Manual recovery tools for stuck provisioning jobs
• Backup/restore support for tenant metadata

Related Use Cases

• UC-001: Trial User Self-Registration - Trial tenants (temporary, auto-expire)
• UC-013: Application Registration and Management - Applications register provisioning endpoints
• UC-015: Application User Provisioning - User creation triggers tenant provisioning
• UC-006: Role-Based Access Control - Tenant-scoped role assignments
• UC-010: Activity Logging and Audit Trail - Tenant lifecycle events logged

Open Questions

1. Should tenant provisioning be synchronous (block user creation) or asynchronous (user created, provisioning background)?

   • Recommendation: Configurable per application. Critical apps (identity) block, non-critical apps async.

2. How do we handle multi-region tenant provisioning (e.g., EU data residency requirements)?

   • Recommendation: Tenant.Metadata includes dataRegion field, applications handle region-specific provisioning.

3. Should we support tenant hierarchies (parent/child organizations)?

   • Recommendation: V2 feature. V1 supports flat tenant structure only.

4. How do we handle tenant migrations between environments (dev → staging → prod)?

   • Recommendation: UC-017: Tenant Migration (separate use case for complex multi-step process).

5. Should billing integration be part of Application Manager or separate service?

   • Recommendation: Separate service. Application Manager sends webhook events to billing system.

6. What happens if user tries to access application that failed provisioning?

   • Recommendation: Show friendly error: "This application is not available. Contact support."

Glossary

• Tenant: Isolated environment for an organization within a multi-tenant application
• Provisioning: Process of creating and initializing a tenant in an application
• Deprovisioning: Process of removing tenant and purging data from application
• Provisioning Webhook: HTTP endpoint implemented by application to handle tenant lifecycle events
• Admin Tenant: Special tenant pre-created for Riptide team members, never expires
• Partial Provisioning: State where tenant is provisioned in some applications but not others
• Grace Period: Time window between suspension and deprovisioning (default 30 days)
• Soft Delete: Marking tenant as deprovisioned but retaining metadata for compliance
• Hard Delete: Permanent deletion of tenant data from applications (after retention period)
• Plan Tier: Subscription level (Free, Starter, Professional, Enterprise)