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

Getting Started

Core Features

Additional Features

Tenant API

Tenant API Documentation

Overview

Base URL

Authentication

Endpoints

Register Tenant

Update Tenant

Get Tenants

Error Responses

Notes

​Tenant API Documentation

​Overview

​Base URL

​Authentication

​Endpoints

​Register Tenant

​Update Tenant

​Get Tenants

​Error Responses

​Notes

Tenant API Documentation

Overview

Base URL

Authentication

Endpoints

Register Tenant

Update Tenant

Get Tenants

Error Responses

Notes