> For the complete documentation index, see [llms.txt](https://docs.digit.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.digit.org/sandbox/specifications/functional-specifications/account-tenant-management.md).

# Account/Tenant Management

## Overview

This page details the functional and technical requirements for managing accounts/tenants, users, tokens (JWT), and handling authentication and authorization within the system. The goal is to standardize APIs, unbundle CITIZEN information from authentication and authorization (Auth\&Auth), and replace user types with predefined roles.

## Features & Scope

The system includes features such as 

* multitenant support
* tenant creation/update/search
* tenant-level authorization
* data isolation, and configuration options for administrators

The Account/Tenant Management system will facilitate the creation, updating, and searching of tenants/accounts within the application. It will enforce tenant-level authorization to ensure data isolation and security. Configuration options will allow administrators to configure tenant-level details like login type, and data isolation approach.

**Click on the below link to learn more about Tenants -** 

## Functional Requirements

### Tenant Management

**Create Tenant:**

Develop an API to allow the creation of new tenants. This API should accept necessary tenant details such as tenant name and contact information.

<figure><img src="https://lh7-rt.googleusercontent.com/docsz/AD_4nXcCTur96HXJsYHE4EZXSWbgxIhYrKuPzNp-HYw9SAnaNW6mfTt2bya3I8aihgZRGIIXuIY1dXC-d0zQof68tVn2U8UsA0aVEMEbFKgeMIVHfvXYS4sqhGWGuxxnu7367yVNiGMZVxmaLvO9UGegUs6LNsY?key=sG-yO7qL-bU-69cbIOk_xA" alt=""><figcaption></figcaption></figure>

<figure><img src="https://lh7-rt.googleusercontent.com/docsz/AD_4nXdwPrxuffPuTPGx_v3J7IAgXeglWMpg-zkdw1ihZYF_1PbpejzWdNAq7szklGkkTWnmjvt8QwR1xpaQHJ123FDc7EttCMtksHrcqWkY7iDZMA01QDNfwNDt6v79mxlVKyriXrI7iuE4MKzJJBEtJYQaVwDU?key=sG-yO7qL-bU-69cbIOk_xA" alt=""><figcaption></figcaption></figure>

<figure><img src="https://lh7-rt.googleusercontent.com/docsz/AD_4nXcD4FRw6CUj-_5F_BV7vmnquktHmRhMD_Xq1FJvXaa5i88w14k5YQ3aNoqmsvlwzxt83v_PjzQjPeUNhM7mIvDMWCk65rc7-5ka_aEuvtBVSkhzKNzCS6hAqwarcb9rKouyuUZO4L47cJigI4Nj_ySveLoB?key=sG-yO7qL-bU-69cbIOk_xA" alt=""><figcaption></figcaption></figure>

Input:&#x20;

| Field       | Type      | Required | Min Length | Max Length | Validations                          |
| ----------- | --------- | -------- | ---------- | ---------- | ------------------------------------ |
| Name        | String    | Y        | 4          | 128        | Allow alphabet only                  |
| Code        | String    | Y        | 2          | 16         | Unique check                         |
| Description | Text Area | N        | 2          | 512        | <p><br></p>                          |
| isActive    | Boolean   | N        | NA         | NA         | Make active after email verification |
| Email       | String    | Y        | 5          | 254        | Email validation                     |

Output: Confirmation message upon successful creation.

1. Send the OTP to the email address&#x20;
2. Verify OTP&#x20;
3. On successful verification create a super user for the tenant
4. Send the super user credentials to the registered email

**Activate Account And Admin User:**

After a user registers in the sandbox, a mail will be sent to the user to verify his email address. Once the user clicks on the link sent in the mail, the email address will be marked as verified and the user will be redirected to the Set Password page.&#x20;

<figure><img src="https://lh7-rt.googleusercontent.com/docsz/AD_4nXf1lONNVIiT0AA-7C-rIym-rhN4eZ_YhEm0wEMf9OtzhTJ4ZcPKg7-9UDOchtZaoB4NurMusUCUlB15oxprneXsFg8-0RJEvrhshl_ZRHqKTKq81cEh2Mpb9ohrJL8JxTZzrJ9ldaQHRdUEf2_JGVAiDCY?key=sG-yO7qL-bU-69cbIOk_xA" alt=""><figcaption></figcaption></figure>

**Open Questions:**&#x20;

1. Should we have an approval process to activate a newly created tenant? Or we can allow self-approval on successful email verification&#x20;

**Update Tenant**

* Description: Ability to update existing tenant information.
* Input: Tenant ID and updated details.
* Output: Confirmation message upon successful update.

**Search Tenants**

* Description: Ability to search for tenants based on criteria.
* Input: Search parameters (name, code).
* Output: List of matching tenants.

## Multi-tenancy

#### Data Isolation

Ensure data isolation between tenants to prevent unauthorized access.

#### **Isolated Database Instances for Tenant Data:**

This approach provides strong data isolation and independence between tenants. It is suitable when tenants require strict data segregation, have diverse infrastructure requirements, or when regulatory compliance demands it.\
\
**Functionality:**

* Provisioning: The client will provision the DB
* Configuration: The client will configure the DB details in the sandbox environment
* Connection Management: Manage database connections dynamically based on the tenant's context.

Pros:

* Strong Isolation: Provides robust isolation between tenants, minimizing the risk of data leakage or unauthorized access.
* Performance: Each database instance can be optimized independently for better performance.

Cons:

* Resource Overhead: Requires additional resources (memory, CPU, storage) to manage multiple database instances.
* Management Complexity: Administrators need to manage and monitor multiple databases, increasing operational overhead.

#### **Tenant-Scoped Schemas within a Shared Database:**

This approach strikes a balance between resource efficiency and data isolation. It is suitable for scenarios where tenants can share the same database infrastructure but still require some level of data segregation. It simplifies management compared to separate databases while providing better isolation than a single shared schema.\
\
**Functionality:**

* Schema Creation: Automatically create a new schema for each new tenant within the shared database.
* Schema Switching: Switch database connections to the appropriate schema based on the authenticated tenant's context.

Pros:

* Resource Efficiency: Utilizes a single database instance, reducing resource overhead compared to separate databases.
* Simplified Management: Centralized management of a single database instance simplifies administration tasks.

Cons:

* Limited Scalability: May face scalability challenges as the number of schemas grows within the shared database.
* Potential for Contention: Resource contention may occur if multiple tenants heavily utilize the shared database.

#### **Unified Schema with Tenant-Tagged Data:**

This approach optimizes resource utilization by sharing the same database schema among all tenants. It is suitable for applications where tenants have similar data access patterns and the ability to filter data based on tenant ID meets the requirements. While it simplifies management and scales well, it may introduce complexity in ensuring data isolation and may impact performance.

## Configuration

#### Data Store Configuration&#x20;

1. Default Data Scheme: Unified Schema with Tenant-Tagged Data (No config required the source details will get fetched from “Master Tenant”)
2. Schema Within Shared Datastore:
   * Configure schema name (Default schema name will be schema name)
   * Configure User Name&#x20;
   * Configure Password
   * The connection URL will be fetched from the Master Tenant
3. Isolated Database:
   * Configure Connection Url
   * Configure Schema Name
   * Configure Username&#x20;
   * Configure Password

#### Login Configuration&#x20;

1. Allowed login types
   * Password
   * OTP
   * 2FA(Password+OTP)
   * Biometric
2. Login Expiry Time(in Sec)
3. Enable social login
4. Enable captcha
5. Password Policy &#x20;

### Sub Tenant

A root tenant admin can create sub-tenants using the Sub Tenant APIs

<figure><img src="https://lh7-rt.googleusercontent.com/docsz/AD_4nXdF4zPf1PCJ0kY_QDWhnCEMg0mXujBSQ-2rYmglP_0BEAzJodlqD2WY4oovurtOWWTXIXE2SMscZOHKezNtXGfwGYTBWz9i1nv7PlXGYi68x-VhV_m10Mx9dXcrQyvxXQrpncwtz6Gc5pqbvQa2SNGq-dVu?key=sG-yO7qL-bU-69cbIOk_xA" alt=""><figcaption></figcaption></figure>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.digit.org/sandbox/specifications/functional-specifications/account-tenant-management.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.