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 REST API endpoints return the following response:

{
  "code": "number", // 0 = success, other = failed
  "message": "string", // the message that illustrates what is wrong
  "data": "object" // the response data. will be `null` when the request is failed, or contains extra error information.
}

For gRPC requests, the response data becomes the object being returned when the request is successful. Otherwise, a gRPC runtime error will be returned.

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:

  {
    "name": "string",
    "adminEmail": "string",
    "businessTypeId": "number"
  }

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

    {
      "id": "number"
    }

Get Tenant Information

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

    {
      "id": "string",
      "name": "string",
      "businessType": "number",
      "createTime": "datetime",
      "updateTime": "datetime"
    }

Update Tenant Information

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

  {
    "name": "string",
    "businessType": "number"
  }

• Response:
  • Status: 200 OK

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
  • Response data object:

    {
      "id": "string"
    }

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/{id}/users
• Method: GET
• Description: Retrieves a list of all users within a tenant.
• Response:
  • Status: 200 OK
  • Response data object:

    {
      "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
  • Response data object:

    {
      "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
  • Response data object:

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