Breadcrumbs

Tenant Management Capabilities in Expertflow CX

Tenant Management in Expertflow CX lets you onboard, update, and manage tenants in a multi‑tenant deployment. It standardizes how tenants are created, how 2FA is configured per tenant, how tokens are generated for tenant‑scoped components, and how tenant‑level statistics are exposed in dashboards.

This guide is intended for Product Managers, Solution Architects, and Backend Developers who design, configure, or consume tenant‑related APIs.

Overview

Tenant Management is a core feature of Expertflow CX that provides:

  • A consistent way to create tenants with their identity, media, and 2FA configuration.

  • Safe update flows where only selected tenant attributes (such as logo or 2FA settings) are changed.

  • A delete operation with clearly defined scope and limitations.

  • A cx-tenant token API that issues tokens bound to a specific tenant.

  • A Login API for the Tenant Portal and components to access tenant APIs.

  • Dashboard APIs that show tenant statistics such as status, new tenants by month, and upcoming expiries.

This feature helps reduce onboarding effort, enforce per‑tenant security (2FA), and give operations a clear view of tenant activity.

Getting Started

To work with Tenant Management, you typically need:

  • Access to the Tenant Management APIs or the Tenant Portal.

  • Keycloak (master realm) connectivity to:

    • Call the Login API.

    • Obtain tokens used with tenant APIs.

  • A reachable OTP Manager at the configured Otp_Manager_Url for tenants with 2FA enabled.

  • Appropriate roles/permissions in your environment to:

    • Create, update, and delete tenants.

    • Read tenant dashboard statistics.

Feature Capability / Functionality

1. Create Tenant

The Create Tenant API is used to onboard a new tenant into Expertflow CX.

What it is

Create Tenant registers a new tenant with all required configuration so that CX components can serve that tenant in an isolated way.

Input data

Create Tenant takes the following data:

  • tenantId
    Unique identifier of the tenant.

  • Keycloak object
    Keycloak‑related configuration for this tenant. This includes identity and token configuration and also contains:

    • Otp_Manager_Url – for example:
      http://ef-cx-otp-manager-svc:3000/
      This is the URL of the OTP Manager service used for 2FA.

  • Campaigns
    Campaign definitions associated with this tenant.

  • Dialer
    Dialer configuration specific to this tenant.

  • Media Server
    Media server configuration for this tenant.

  • 2FA Config (must have)
    Two‑factor authentication configuration. This object must always be provided on create.

    • When isEnabled = true:

      • channelType – SMS or Email

      • serviceIdentifier – identifier of the configured SMS/Email service

      • OTP Expiry – validity duration for each OTP

      • Retry Limits – maximum allowed OTP retry attempts

    • When isEnabled = false:

      • 2FA is disabled for this tenant.

      • The other 2FA fields are treated as null and are not used.

  • Tenant Logo
    Logo used for branding the tenant (for example in the tenant portal).

How it works

  • The API receives a full tenant configuration payload.

  • It validates:

    • Required fields such as tenantId, Keycloak object, and 2FA Config.

    • Consistency of 2FA settings (if enabled, all related fields must be present).

  • It persists the tenant and its configuration so CX components can:

    • Authenticate and authorize users and services per tenant.

    • Use the correct media server, campaigns, and dialer configuration.

    • Use the OTP Manager (via Otp_Manager_Url) for 2FA flows.

Business value

  • Provides a consistent and repeatable way to onboard new tenants.

  • Ensures that 2FA rules, media, and dialer configuration are correctly bound to each tenant.

  • Reduces manual errors by enforcing a structured payload for new tenants.

2. Update Tenant

The Update Tenant API modifies selected properties of an existing tenant. It is explicitly designed for partial updates.

What it is

Update Tenant lets you change aspects of a tenant without recreating it. Only the provided fields are updated; all other fields remain as they are.

Updatable data

The same high‑level structure as Create Tenant exists, but only the following fields can be updated:

  • Media Server

  • 2FA Config (must have in update payload)

    • If isEnabled = true:

      • channelType (SMS, Email)

      • serviceIdentifier

      • OTP Expiry

      • Retry Limits

    • If isEnabled = false:

      • Other 2FA fields are treated as null.

  • Otp_Manager_Url

    • Can be updated to point to a different OTP Manager service.

  • Tenant Logo

Other fields (for example tenantId) are not updated via this API.

Partial update behavior

  • If you provide only the logo, the API updates the logo only.

  • If you provide only settings (for example, Media Server and 2FA Config), it updates only those settings.

  • If you provide both settings and logo, all provided values are updated.

This behavior ensures you do not have to send the complete tenant configuration on every update and reduces risk of accidental overwrites.

Business value

  • Allows safe updates to tenant branding and security policies.

  • Lets you enable or disable 2FA at any time and adjust OTP expiry and retry policies.

  • Supports infrastructure changes, such as moving a tenant to a different media server or OTP Manager URL.

3. Delete Tenant

The Delete Tenant API removes a tenant at the tenant‑management level.

What it is

Delete Tenant is used when a tenant is no longer required or should no longer be active in Expertflow CX.

How it works

  • The API marks or removes the tenant so that:

    • It is no longer considered an active tenant.

    • Tenant login and usage are stopped according to implementation.

Limitation

  • Delete Tenant does not fully clean everything.
    It does not guarantee:

    • Deletion of all related data across all systems.

    • Removal of all logs, records, or external resources tied to that tenant.

In practice, this is a logical or partial delete. Additional cleanup operations or retention policies may apply depending on your deployment and compliance requirements.

Business value

  • Provides a controlled way to retire tenants.

  • Clarifies that downstream cleanup may need to be handled separately.

4. cx‑tenant Token API

A new API is available to generate tenant‑scoped tokens for core components.

What it is

The cx‑tenant API issues tokens that are bound to a specific tenant, for example:

  • Input concept: cx-tenant tenant1

  • Resulting tenant context: tenant.expertflow.com

Core components use this API to obtain tokens that identify which tenant they are operating for.

How it works

  • A component calls the cx‑tenant API with the tenant identifier (such as tenant1).

  • The API generates a token that:

    • Is scoped to that tenant.

    • Can be used by core components to call CX services that must respect tenant isolation.

Business value

  • Ensures strict tenant isolation at the token and service layer.

  • Simplifies how backend services get tenant‑specific tokens without each service having to manage tenant configuration itself.

5. Login API (Keycloak – master)

The Login API is used by the Tenant Portal and any component that wants to access tenant APIs.

What it is

This API authenticates against Keycloak’s master realm and returns a token that can be used to call tenant management and tenant‑level APIs.

How it works

  • The Tenant Portal (or another component) calls the Login API against the Keycloak master realm.

  • Keycloak validates the credentials.

  • A token is returned that:

    • Allows the tenant portal to log in.

    • Can be used to call tenant-related APIs, depending on assigned roles and permissions.

Business value

  • Provides a standard login mechanism for the tenant portal.

  • Centralizes authentication using Keycloak master, simplifying token issuance for tenant management operations.

6. Dashboard APIs

Dashboard APIs are used to fetch tenant‑related statistics for display on the tenant portal dashboard.

What it is

These APIs return aggregated information about tenants that is useful for monitoring and reporting.

What they show

Typical statistics include:

  • List of tenants with status

    • For example: Active / Inactive.

  • New tenants by month

    • Shows how many tenants were created in each month.

  • Upcoming expiries

    • Tenants that are close to their subscription or contract expiry dates.

The tenant portal uses these APIs to render overview tiles, charts, and lists.

Business value

  • Gives administrators and business stakeholders visibility into tenant lifecycle and health.

  • Helps identify:

    • Growth trends (new tenants by month).

    • Inactive tenants.

    • Tenants due for renewal or follow‑up.

Limitations

  • Delete Tenant is not a deep purge

    • It does not remove all downstream resources or historical data.

    • Additional manual or automated cleanup might be required.

  • 2FA is limited to SMS and Email

    • 2FAcan be enabled only for one channel at a time

  • Dependency on OTP Manager

    • For tenants with 2FA enabled, Otp_Manager_Url must be valid and reachable.

    • If the OTP Manager service is down, OTP issuance and validation will fail.

FAQs (Good to Have)

Q1. Is the 2FA Config mandatory?
Yes. The 2FA Config object must be part of both Create Tenant and Update Tenant requests.

  • If isEnabled = true, all 2FA fields (channelType, serviceIdentifier, OTP Expiry, Retry Limits) must be provided.

  • If isEnabled = false, those fields are treated as null.

Q2. Can I update only the tenant logo?
Yes. If the update payload includes only the logo, only the logo is updated. Media Server, 2FA Config, and Otp_Manager_Url remain unchanged.

Q3. What remains after I delete a tenant?
Delete Tenant stops the tenant from being active, but it does not guarantee that all related data (logs, history, external resources) is removed. Some data may remain according to your retention and compliance policies.

Q4. How do core components get a tenant‑scoped token?
Core components call the cx‑tenant API with the tenant identifier (for example, tenant1). The API returns a token bound to that tenant (e.g., for tenant.expertflow.com), which can then be used for calls that must respect tenant isolation.

Q5. How does the Tenant Portal authenticate?
The Tenant Portal uses the Login API against Keycloak’s master realm. The returned token lets the portal log in and call tenant management and tenant APIs as permitted by its roles.