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:

{
  "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:

{
  "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:

{
  "fullName": "string",
  "phoneNumber": "string",
  "email": "string",
  "country": "string"
}

Response:

{
  "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:

{
  "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:

{
  "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

{
  "statusCode": 401,
  "message": "Unauthorized",
  "data": null
}

404 Not Found

{
  "statusCode": 404,
  "message": "User not found",
  "data": null
}

409 Conflict

{
  "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

Getting Started

Core Features

Additional Features

User API

User API Documentation

Overview

Base URL

Authentication

Endpoints

Create User

Update User

Get Users

Activate/Deactivate User

Error Responses

Notes

​User API Documentation

​Overview

​Base URL

​Authentication

​Endpoints

​Create User

​Update User

​Get Users

​Activate/Deactivate User

​Error Responses

​Notes

User API Documentation

Overview

Base URL

Authentication

Endpoints

Create User

Update User

Get Users

Activate/Deactivate User

Error Responses

Notes