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

{
  "code": "number", // 0 = success, other = failed
  "message": "string", // the message that illustrates what is wrong
  "data": "object" // the response data, null when the request is failed
}

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

Navigation Menu