Skip to main content

Tenant Operations

Gateway prefix: ${API_BASE}/metadata/ops/tenants/...

Request email verification code​

  • POST /ops/tenants/email/verify/request

Request body:

  • email string, required, email address to receive the code

Example request:

curl -X POST \
  "${API_BASE}/metadata/ops/tenants/email/verify/request" \
  -H "Content-Type: application/json" \
  -d '{"email":"user@example.com"}'

Example response:

{
  "success": true,
  "message": "OK",
  "data": null
}

New tenant registration​

  • POST /ops/tenants/seed-admin

Request body: CreateTenantAdminRequest

  • username string, required, admin username
  • email string (email), required, admin email
  • code string, required, 6-digit email verification code
  • password string, optional, Keycloak admin password (generated if omitted)
  • dbPassword string, optional, self-hosted DB password (generated if omitted)
  • initSample boolean, optional, default true, whether to initialize sample data and metadata

Response: ApiResponse<String>, data is generated tenantId.

Common combinations:

  • Simplest registration (system-generated password, with sample data): username + email + code + initSample=true
  • Custom admin password: additionally provide password
  • Custom DB password: additionally provide dbPassword
  • Skip samples: initSample=false

Example request:

curl -X POST \
  "${API_BASE}/metadata/ops/tenants/seed-admin" \
  -H "Content-Type: application/json" \
  -d '{
    "username":"alice",
    "email":"user@example.com",
    "code":"123456",
    "initSample": true
  }'

Example response:

{
  "success": true,
  "message": "Tenant <tenantId> admin user <username> scheduled. Password sent to <email>.",
  "data": "abc12345"
}

Error example: invalid or expired verification code:

{
  "success": false,
  "message": "Verification code incorrect or expired",
  "errorCode": "EMAIL_VERIFY_FAILED"
}

Fast tenant creation by phone (no verification code)​

  • POST /ops/tenants/seed-admin/phone

Request body: CreateTenantByPhoneRequest

  • username string, required, recommended to use phone number as admin username
  • initSample boolean, optional, default true

Response: ApiResponse<Map>, data includes tenantId and other info (see actual response).

Example:

curl -X POST \
  "${API_BASE}/metadata/ops/tenants/seed-admin/phone" \
  -H "Content-Type: application/json" \
  -d '{
    "username":"13800138000",
    "initSample": true
  }'

Query tenants by phone​

  • GET /ops/tenants/by-phone?phone=<phone>

Response: ApiResponse<List<{id,name}>>

Example:

curl -X GET \
  "${API_BASE}/metadata/ops/tenants/by-phone?phone=13800138000"