How to Use User Management APIs

This guide describes how to create, search, update, and manage users inside Fabrixly-IDS using the User Management REST APIs.

🔐 Authentication & Prerequisites

All user management endpoints require administrative authentication. To call them:

1. Include the Token in the Authorization Header: Add -H "Authorization: Bearer <your-admin-jwt-token>" to your API calls.

Obtain an Admin JWT Token:

curl -X POST https://ids.fabrixly.com/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "admin@example.com",
    "password": "your-admin-password"
  }'

Note: This returns a JSON response containing a token.

1. Create a User (Registration)

Registers a new user in the organization.

• HTTP Method: POST
• Path: /api/users
• Headers:
  • Content-Type: application/json
  • Authorization: Bearer <your-admin-jwt-token>

Request Body Parameters

Example Request (curl)

curl -X POST https://ids.fabrixly.com/api/users \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your-admin-jwt-token>" \
  -d '{
    "email": "newuser@example.com",
    "password": "strong-password-123",
    "organizationId": "org_xyz789abc",
    "firstName": "John",
    "lastName": "Doe",
    "mobile": "+1234567890",
    "country": "US",
    "roleNames": ["USER", "SUPPORT_STAFF"],
    "teamNames": ["Engineering Support Team"]
  }'

Response (201 Created)

{
  "id": "usr_789abc123",
  "email": "newuser@example.com",
  "firstName": "John",
  "lastName": "Doe",
  "mobile": "+1234567890",
  "country": "US",
  "email_verified": false,
  "status": "active"
}

Error Responses

400 Bad Request (Invalid or missing password/organization)

{
  "error": "Password is required for new users"
}

403 Forbidden (Requires Org Admin or Team Admin role, or attempting to add user to a different organization)

{
  "error": "Forbidden: Cannot add user to another organization"
}

2. List & Query Users

Search and paginate registered users.

• HTTP Method: GET
• Path: /api/users
• Query Parameters:
  • page: (integer) Page number (default: 1).
  • limit: (integer) Page size limit (default: 10).
  • search: (string) Filter by email/name query.
• Headers:
  • Authorization: Bearer <your-admin-jwt-token>

Example Request (curl)

curl -X GET "https://ids.fabrixly.com/api/users?page=1&limit=5&search=John" \
  -H "Authorization: Bearer <your-admin-jwt-token>"

Response (200 OK)

{
  "users": [
    {
      "id": "usr_789abc123",
      "email": "newuser@example.com",
      "firstName": "John",
      "lastName": "Doe"
    }
  ],
  "total": 1,
  "pages": 1
}

3. Get User Details

• HTTP Method: GET
• Path: /api/users/:id
• Headers:
  • Authorization: Bearer <your-admin-jwt-token>

Example Request (curl)

curl -X GET https://ids.fabrixly.com/api/users/usr_789abc123 \
  -H "Authorization: Bearer <your-admin-jwt-token>"

4. Update User Profile

Modifies a user's basic profile details.

• HTTP Method: PUT
• Path: /api/users/:id
• Headers:
  • Content-Type: application/json
  • Authorization: Bearer <your-admin-jwt-token>

Example Request (curl)

curl -X PUT https://ids.fabrixly.com/api/users/usr_789abc123 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your-admin-jwt-token>" \
  -d '{
    "firstName": "Johnathan",
    "mobile": "+1987654321"
  }'

5. Update Password

Updates a user's password securely (performs automatic bcrypt hashing).

• HTTP Method: PUT
• Path: /api/users/:id/password
• Headers:
  • Content-Type: application/json
  • Authorization: Bearer <your-admin-jwt-token>

Example Request (curl)

curl -X PUT https://ids.fabrixly.com/api/users/usr_789abc123/password \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your-admin-jwt-token>" \
  -d '{
    "password": "my-new-secure-password-456"
  }'

Response (200 OK)

{
  "message": "Password updated successfully"
}

6. Update Security Settings (2FA & Passwordless)

Enables or disables multi-factor authentication (MFA), preferred methods, and passwordless logins.

• HTTP Method: PUT
• Path: /api/users/:id/security
• Headers:
  • Content-Type: application/json
  • Authorization: Bearer <your-admin-jwt-token>

Request Body Parameters

• enable_2fa: (boolean) Enable/disable MFA.
• preferred_2fa_method: (string) email, sms, or totp.
• disable_password_login: (boolean) Set true to enforce passwordless flow.

Example Request (curl)

curl -X PUT https://ids.fabrixly.com/api/users/usr_789abc123/security \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your-admin-jwt-token>" \
  -d '{
    "enable_2fa": true,
    "preferred_2fa_method": "email",
    "disable_password_login": false
  }'

7. Generate Backup Codes

Generates standard emergency backup codes for multi-factor recovery.

• HTTP Method: POST
• Path: /api/users/:id/backup-codes
• Headers:
  • Authorization: Bearer <your-admin-jwt-token>

Example Request (curl)

curl -X POST https://ids.fabrixly.com/api/users/usr_789abc123/backup-codes \
  -H "Authorization: Bearer <your-admin-jwt-token>"

Response (200 OK)

{
  "backupCodes": [
    "abcd-1234",
    "efgh-5678",
    "ijkl-9012"
  ]
}

8. Delete User

Deletes a user account from the system database.

• HTTP Method: DELETE
• Path: /api/users/:id
• Headers:
  • Authorization: Bearer <your-admin-jwt-token>

Example Request (curl)

curl -X DELETE https://ids.fabrixly.com/api/users/usr_789abc123 \
  -H "Authorization: Bearer <your-admin-jwt-token>"

Response (200 OK)

{
  "message": "User deleted successfully"
}