> ## Documentation Index
> Fetch the complete documentation index at: https://dvaultdocs.dukka.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Tenant API

> Manage multi-tenant configurations and settings

# 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:**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "name": "string",
  "phoneNumber": "string",
  "address": "string",
  "allowNotification": "boolean",
  "webhookUrl": "string"
}
```

**Response:**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "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**

```json theme={null}
{
  "statusCode": 401,
  "message": "Unauthorized",
  "data": null
}
```

**404 Not Found**

```json theme={null}
{
  "statusCode": 404,
  "message": "Tenant not found",
  "data": null
}
```

**409 Conflict**

```json theme={null}
{
  "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