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.

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
  • Body:

    {
      "tenantId": "string",
      "message": "Tenant created successfully."
    }

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."
    }