Multi‐Tenant System API Documentation

Multi-Tenant System API Documentation

Overview

This document provides an overview and detailed description of the essential APIs for a multi-tenant system. These APIs cover the management of tenants, users, permissions, and authentication processes, following RESTful principles, secure practices, and clear error handling.

Response Schema

All the standard HTTP API points return the following response:

{
  "code": "number",
  "message": "string",
  "data": "object"
}

Tenant Management APIs

New Tenant Registration

• Endpoint: /api/v1/tenants
• Method: POST
• Description: Allows a new user to register and create a new tenant.
• Request Body:

  {
    "tenantName": "string",
    "adminEmail": "string",
    "businessType": "string"
  }

• Response:
  • Status: 201 Created
  • Response data object:

    {
      "tenantId": "number"
    }

Get Tenant Information

• Endpoint: /api/v1/tenants/{tenantId}
• Method: GET
• Description: Provides detailed information about a specific tenant.
• Response:
  • Status: 200 OK
  • Body:

    {
      "tenantId": "string",
      "tenantName": "string",
      "createdDate": "datetime",
      "adminEmail": "string",
      "businessType": "string"
    }

Update Tenant Information

• Endpoint: /api/v1/tenants/{tenantId}
• Method: PUT
• Description: Updates information of a tenant.
• Request Body:

  {
    "tenantName": "string",
    "businessType": "string"
  }

• Response:
  • Status: 200 OK
  • Body:

    {
      "message": "Tenant updated successfully."
    }

User Management APIs

User Registration/Creation

• Endpoint: /api/v1/users
• Method: POST
• Description: Registers a new user in the system.
• Request Body:

  {
    "email": "string",
    "password": "string",
    "tenantId": "string"
  }

• Response:
  • Status: 201 Created
  • Body:

    {
      "userId": "string",
      "message": "User registered successfully."
    }

User Login

• Endpoint: /api/v1/users/login
• Method: POST
• Description: User login to obtain access token.
• Request Body:

  {
    "email": "string",
    "password": "string"
  }

• Response:
  • Status: 200 OK
  • Body: { "token": "string" }

Get User List

• Endpoint: /api/v1/tenants/{tenantId}/users
• Method: GET
• Description: Retrieves a list of all users within a tenant.
• Response:
  • Status: 200 OK
  • Body:

    {
      "users": [
        {
          "userId": "string",
          "email": "string",
          ...
        },
        ...
      ]
    }

Permissions and Role Management APIs

Get Role List

• Endpoint: /api/v1/roles
• Method: GET
• Description: Retrieves a list of all roles defined in the system.
• Response:
  • Status: 200 OK
  • Body:

    {
      "roles": ["role1", "role2", ...]
    }

Assign Roles

• Endpoint: /api/v1/users/{userId}/roles
• Method: POST
• Description: Assigns roles to a specific user.
• Request Body:

  {
    "roles": ["role1", "role2", ...]
  }

• Response:
  • Status: 200 OK
  • Body: { "message": "Roles assigned successfully." }

Authentication and Authorization APIs

Token Validation

• Endpoint: /api/v1/auth/validate
• Method: POST
• Description: Validates a user's access token.
• Request Body:

  {
    "token": "string"
  }

• Response:
  • Status: 200 OK
  • Body:

    {
      "isValid": "boolean",
      "userId": "string",
      "message": "Token is valid."
    }