Skip to main content

​
Tenant API Documentation

​
Overview

The Tenant API provides endpoints for managing tenants in the wallet service, including creation, updates, and tenant management operations.

​
Base URL

/api/v1/tenants

​
Authentication

All endpoints require authentication using an API key in the request headers:
  • X-API-KEY: Your API key
  • X-Tenant-ID: Tenant identifier (required for most endpoints)

​
Endpoints

​
Register Tenant

Create a new tenant with an admin user. Endpoint: POST /register Headers:
  • X-API-KEY (optional): API key for authentication
Request Body: 
{
  "tenant": {
    "name": "string",
    "email": "string",
    "phoneNumber": "string",
    "address": "string",
    "country": {
      "code": "string",
      "name": "string"
    },
    "allowNotification": "boolean",
    "webhookUrl": "string"
  },
  "tenantAdmin": {
    "fullName": "string",
    "phoneNumber": "string",
    "password": "string",
    "email": "string",
    "country": {
      "code": "string",
      "name": "string"
    },
    "type": "TENANT_ADMIN",
    "keyDuration": "number",
    "duration": "HOURS|DAYS|WEEKS|MONTHS|YEARS"
  }
}
Response: 
{
  "statusCode": 201,
  "message": "string",
  "data": {
    "tenantId": "string",
    "name": "string",
    "email": "string",
    "phoneNumber": "string",
    "address": "string",
    "country": {
      "code": "string",
      "name": "string"
    },
    "allowNotification": "boolean",
    "webhookUrl": "string",
    "tenantAdmin": {
      "userId": "string",
      "fullName": "string",
      "phoneNumber": "string",
      "email": "string",
      "country": "string",
      "createdAt": "string",
      "updatedAt": "string",
      "type": "string",
      "tenantId": "string"
    }
  }
}

​
Update Tenant

Update an existing tenant’s information. Endpoint: POST /update Headers:
  • X-API-KEY (optional): API key for authentication
  • X-Tenant-ID: Tenant identifier
Request Body: 
{
  "name": "string",
  "phoneNumber": "string",
  "address": "string",
  "allowNotification": "boolean",
  "webhookUrl": "string"
}
Response: 
{
  "statusCode": 200,
  "message": "string",
  "data": {
    "tenantId": "string",
    "name": "string",
    "email": "string",
    "phoneNumber": "string",
    "address": "string",
    "country": {
      "code": "string",
      "name": "string"
    },
    "allowNotification": "boolean",
    "webhookUrl": "string"
  }
}

​
Get Tenants

Retrieve tenants with filtering and pagination. Endpoint: GET / Headers:
  • X-API-KEY (optional): API key for authentication
Query Parameters:
  • tenantId: Filter by tenant ID (comma-separated for multiple IDs)
  • name: Filter by tenant name (comma-separated for multiple names)
  • email: Filter by email (comma-separated for multiple emails)
  • country: Filter by country code (comma-separated for multiple countries)
  • allowNotification: Filter by notification status
  • page: Page number (default: 0)
  • size: Page size (default: 20)
  • sort: Sort field and direction (e.g., “createdAt,desc”)
Response: 
{
  "statusCode": 200,
  "message": "string",
  "data": {
    "content": [
      {
        "tenantId": "string",
        "name": "string",
        "email": "string",
        "phoneNumber": "string",
        "address": "string",
        "country": {
          "code": "string",
          "name": "string"
        },
        "allowNotification": "boolean",
        "webhookUrl": "string"
      }
    ],
    "totalElements": "number",
    "totalPages": "number",
    "size": "number",
    "number": "number"
  }
}

​
Error Responses

All endpoints may return the following error responses: 401 Unauthorized 
{
  "statusCode": 401,
  "message": "Unauthorized",
  "data": null
}
404 Not Found 
{
  "statusCode": 404,
  "message": "Tenant not found",
  "data": null
}
409 Conflict 
{
  "statusCode": 409,
  "message": "Duplicate tenant email",
  "data": null
}

​
Notes

  • All timestamps are in ISO-8601 format
  • Tenant registration:
    • Creates a new tenant with a unique ID
    • Creates a tenant admin user
    • Generates API keys for the admin user
    • Sends onboarding notifications
  • Tenant updates:
    • Only tenant admins can update their tenant
    • Platform admins can update any tenant
    • Regular users cannot update tenant information
  • Tenant viewing:
    • Platform admins can view all tenants
    • Tenant admins can only view their own tenant
    • Regular users cannot view tenant information
  • Email addresses must be unique across the system
  • Phone numbers must be valid for the specified country
  • Webhook URLs must be valid HTTPS URLs
  • Notification settings can be toggled per tenant
  • Tenant history is maintained for audit purposes
  • Deleted tenants are soft-deleted and can be restored