> ## 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.

# User API

> Manage user accounts and profiles

# User API Documentation

## Overview

The User API provides endpoints for managing users in the wallet service, including creation, updates, and user management operations.

## Base URL

`/api/v1/users`

## 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)
* `countryCode`: Country code (required for user creation)

## Endpoints

### Create User

Create a new user in the system.

**Endpoint:** `POST /register`

**Headers:**

* `X-API-KEY` (optional): API key for authentication
* `X-Tenant-ID`: Tenant identifier
* `countryCode`: Country code

**Request Body:**

```json theme={null}
{
  "fullName": "string",
  "phoneNumber": "string",
  "password": "string",
  "email": "string",
  "country": {
    "code": "string",
    "name": "string"
  },
  "type": "TENANT_ADMIN|TENANT_USER",
  "keyDuration": "number",
  "duration": "HOURS|DAYS|WEEKS|MONTHS|YEARS"
}
```

**Response:**

```json theme={null}
{
  "statusCode": 201,
  "message": "string",
  "data": {
    "id": "number",
    "userId": "string",
    "tenant": {
      "tenantId": "string",
      "name": "string"
    },
    "fullName": "string",
    "phoneNumber": "string",
    "email": "string",
    "country": "string",
    "type": "string",
    "active": "boolean",
    "deleted": "boolean",
    "createdAt": "string",
    "updatedAt": "string"
  }
}
```

### Update User

Update an existing user's information.

**Endpoint:** `PATCH /update`

**Headers:**

* `X-API-KEY` (optional): API key for authentication
* `X-Tenant-ID`: Tenant identifier

**Request Body:**

```json theme={null}
{
  "fullName": "string",
  "phoneNumber": "string",
  "email": "string",
  "country": "string"
}
```

**Response:**

```json theme={null}
{
  "statusCode": 200,
  "message": "string",
  "data": {
    "id": "number",
    "userId": "string",
    "tenant": {
      "tenantId": "string",
      "name": "string"
    },
    "fullName": "string",
    "phoneNumber": "string",
    "email": "string",
    "country": "string",
    "type": "string",
    "active": "boolean",
    "deleted": "boolean",
    "createdAt": "string",
    "updatedAt": "string"
  }
}
```

### Get Users

Retrieve users with filtering and pagination.

**Endpoint:** `GET /`

**Headers:**

* `X-API-KEY` (optional): API key for authentication
* `X-Tenant-ID` (optional): Tenant identifier

**Query Parameters:**

* `userId`: Filter by user ID (comma-separated for multiple IDs)
* `tenantId`: Filter by tenant ID
* `fullName`: Filter by full name
* `phoneNumber`: Filter by phone number (comma-separated for multiple numbers)
* `email`: Filter by email
* `country`: Filter by country code (comma-separated for multiple countries)
* `type`: Filter by user type (comma-separated for multiple types)
* `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": [
      {
        "userId": "string",
        "fullName": "string",
        "phoneNumber": "string",
        "email": "string",
        "country": "string",
        "createdAt": "string",
        "updatedAt": "string",
        "type": "string",
        "tenantId": "string"
      }
    ],
    "totalElements": "number",
    "totalPages": "number",
    "size": "number",
    "number": "number"
  }
}
```

### Activate/Deactivate User

Activate or deactivate a user account.

**Endpoint:** `GET /{userId}/{action}`

**Headers:**

* `X-API-KEY` (optional): API key for authentication
* `X-Tenant-ID` (optional): Tenant identifier

**Path Parameters:**

* `userId`: User ID
* `action`: Action to perform (ACTIVATE or DEACTIVATE)

**Response:**

```json theme={null}
{
  "statusCode": 200,
  "message": "string",
  "data": {
    "id": "number",
    "userId": "string",
    "tenant": {
      "tenantId": "string",
      "name": "string"
    },
    "fullName": "string",
    "phoneNumber": "string",
    "email": "string",
    "country": "string",
    "type": "string",
    "active": "boolean",
    "deleted": "boolean",
    "createdAt": "string",
    "updatedAt": "string"
  }
}
```

## 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": "User not found",
  "data": null
}
```

**409 Conflict**

```json theme={null}
{
  "statusCode": 409,
  "message": "Duplicate email",
  "data": null
}
```

## Notes

* All timestamps are in ISO-8601 format
* User types:
  * TENANT\_ADMIN: Can manage users within their tenant
  * TENANT\_USER: Regular user within a tenant
* Platform admins can create users for any tenant
* Tenant admins can only create users for their own tenant
* Regular users can only update their own profile
* User activation/deactivation:
  * Platform admins can activate/deactivate any user
  * Tenant admins can only activate/deactivate users in their tenant
  * Regular users cannot activate/deactivate accounts
* Email addresses must be unique across the system
* Phone numbers must be valid for the specified country
* User passwords are encrypted before storage
* API keys are automatically generated for new users
* User history is maintained for audit purposes
* Deleted users are soft-deleted and can be restored