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.
• Authentication: No authentication required.
• Request Body:

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

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

    {
      "id": "number",
      "adminUser": {
         "id": "number",
         "email": "string",
         "password": "string"
      }
    }

Get Tenant Information

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

    {
      "id": "string",
      "name": "string",
      "businessTypeId": "number",
      "createdAt": "datetime",
      "updatedAt": "datetime"
    }

Update Tenant Information

• Endpoint: /api/v1/tenants/{id}
• Method: PATCH
• Description: Updates information of a tenant.
• Authentication: Permission tenant:update is required.
• Request Body:

  {
    "name": "string",
    "businessTypeId": "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.
• Authentication: No authentication required.
• Request Body:

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

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

    {
      "id": "number"
    }

User Login

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

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

• Response:
  • Status: 200 OK
  • Response data object:

    {
      "id": "number",
      "tenantId": "number",
      "accessToken": {
        "token": "string",
        "type": "string",
        "expiresAt": "datetime"
      },
      "refershToken": {
        "token": "string",
        "expiresAt": "datetime"
      }
    }

Get User List

• Endpoint: /api/v1/tenants/{id}/users
• Method: GET
• Description: Retrieves a list of all users within a tenant.
• Authentication: Permission tenant:list_users is required.
• Response:
  • Status: 200 OK
  • Response data object:

    [
        {
          "userId": "string",
          "email": "string",
          "name": "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.
• Authentication: No authentication required.
• Response:
  • Status: 200 OK
  • Response data object:

    ["role1", "role2", ...]

Assign Roles

• Endpoint: /api/v1/users/{userId}/roles
• Method: POST
• Description: Assigns roles to a specific user.
• Authentication: Permission tenant:manage_users is required.
• Request Body:

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

• Response:
  • Status: 200 OK

Authentication and Authorization APIs

Token Validation

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

  {
    "token": "string"
  }

• Response when token is valid:
  • Status: 200 OK
  • Response data object:

    {
      "userId": "string"
    }

• Response when token is invalid:
  • Status: 401 Unauthorized