HomeReference

Admin - User

User Management provides capabilities for inviting, searching, updating, and removing users across your organization. Use these endpoints to onboard new team members to specific tenants, manage user profiles and roles, search for users by email, and handle user lifecycle operations like deletion or tenant transfers

Invite Users to Tenant

Invite one or more users to a specific tenant. They receive an email invitation to join the platform. Once they accept, they become active users within the specified tenant with access to the assigned role's permissions.

Tenant User Roles

When inviting users to a tenant, you can assign them a role_name that determines their default access and capabilities. The available roles are:

  • client_admin: Full administrative access including user management, tenant settings, and the ability to invite other users to the tenant

  • general_user: Standard user access with permissions to use AI chat, create and manage apps, and access the app builder interface. default

  • chat_only_user: Limited access restricted to the secure AI chat functionality without app creation or builder capabilities

  • workshop_user: Access to view and use existing apps in the workshop but cannot create, copy, or delete apps

For detailed information about permissions included in each role, see the Tenant User Roles documentation

Endpoint: POST /v1/admin/users/invite
Request:
{
  "tenant_id": "string",      // Required: Tenant ID (e.g., "tenant_ZG1VvZ8qY0rOLUKxllexWrekN8")
  "users": [                   // Required: Array of users to invite (1-100, no duplicates)
    {
      "email": "string",
      "first_name": "string",  // Optional
      "last_name": "string",   // Optional
      "role": "string"         // Optional, defaults to general_user
    }
  ]
Example Query
curl 'https://ai.hatz.ai/v1/admin/users/invite' \
-H 'X-API-Key: $HATZ_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
  "tenant_id": $TENANT_ID,
  "users": [
    {
      "email": "user@example.com",
      "first_name": "First",
      "last_name": "Last"
    }
  ]
}'
Response
{
  "message": "Successfully created 1 user(s)",
  "total_new_users_created": 1,
  "total_new_users_failed": 0,
  "new_users_failed_emails": [],
  "results": [
    {
      "email": "user@example.com",
      "success": true,
      "error": null
    }
  ]
}

Invite Internal Admin Users

Invite users to the internal admin entity (MSP).

Admin-Level (MSP) User Roles

When inviting users to the internal admin entity (MSP), you can assign them a role_name for admin.hatz.ai access. The available roles are:

  • primary_admin: Full MSP administrative control including creating tenants, purchasing packages, managing all users, publishing apps to all tenants, and accessing billing (cannot be deleted by other admins)

  • admin: Same permissions as primary_admin including tenant creation, package purchases, user management, and billing access (can be deleted by primary_admin)

  • billing manager: Limited access to view billing portal details and user roles without modification capabilities

  • helpdesk: Support role with permissions to add users and view all tenant apps but without administrative or billing access

For detailed information about MSP admin roles, see the Admin Account User Roles documentation

Endpoint: POST /v1/admin/users/invite/internal-admin
Request Body:
{
  "users": [                   // Required: Array of users to invite (1-100, no duplicates)
    {
      "email": "string",
      "first_name": "string",  // Optional
      "last_name": "string",   // Optional
      "role": "string"         // Optional, default to helpdesk
    }
  ]
Example Query
curl 'https://ai.hatz.ai/v1/admin/users/invite/internal-admin' \
-H 'X-API-Key: $HATZ_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
  "users": [
    {
      "email": "user@example.com",
      "first_name": "First",
      "last_name": "Last"
    }
  ]
Response
{
  "message": "Successfully created 1 user(s)",
  "total_new_users_created": 1,
  "total_new_users_failed": 0,
  "new_users_failed_emails": [],
  "results": [
    {
      "email": "user@example.com",
      "success": true,
      "error": null
    }
  ]
}

Search User by Email

Search for a user by their email address.

Endpoint: GET /v1/admin/users
Path Parameters:

- email: User email

Example Query

curl 'https://ai.hatz.ai/v1/admin/users?email=user@example.com' \
-H 'X-API-Key: $HATZ_API_KEY'

Response

Returns the user if found, or null if not found:

{
  "id": "user_<hashid>",
  "email": "user@example.com",
  "first_name": "First",
  "last_name": "Last",
  "tenant_id": "tenant_<hashid>",
  "role_name": "general_user",
  "last_sign_in_at": "2024-12-01T10:30:00Z"
}

Get User Details

Retrieve details for a specific user by ID.

Endpoint: GET /v1/admin/users/{user_id}
Path Parameters:

- user_id: User ID (e.g., "user_<hashid>")

Example Query
curl 'https://ai.hatz.ai/v1/admin/users/user_<hashid>' \
-H 'X-API-Key: $HATZ_API_KEY'
Response
{
  "id": "user_<hashid>",
  "email": "user@example.com",
  "first_name": "First",
  "last_name": "Last",
  "tenant_id": "tenant_<hashid>",
  "role_name": "general_user",
  "last_sign_in_at": "2024-12-01T10:30:00Z"
}

Delete User

Remove a user from their tenant.

Endpoint: DELETE /v1/admin/users/{user_id}
Path Parameters:

- user_id: UserID to delete

Example Query
curl -X DELETE 'https://ai.hatz.ai/v1/admin/users/user_<hashid>' \
-H 'X-API-Key: $HATZ_API_KEY'

Response

{
  "message": "User deleted successfully",
  "user_id": "user_<hashid>"
}

Update User

Update a user's profile, role, or move them to a different tenant. You can move between tenants but you cannot move a user into your internal admin account.

Endpoint: PATCH /v1/admin/users/{user_id}
Path Parameters:

- user_id: User ID to update

Request Body:
{

  "first_name": "string",    // Optional: Update first name
  "last_name": "string",     // Optional: Update last name
  "role_name": "string",     // Optional: Change user's role
  "tenant_id": "string"      // Optional: Move user to this tenant (id)
}

> Note: At least one field must be provided. All fields are optional - provide only the fields you want to update.

Example Queries

Update name:

curl -X PATCH 'https://ai.hatz.ai/v1/admin/users/user_<hashid>' \
-H 'X-API-Key: $HATZ_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
  "first_name": "John",
  "last_name": "Smith"
}'

Change role:

curl -X PATCH 'https://ai.hatz.ai/v1/admin/users/user_<hashid>' \
-H 'X-API-Key: $HATZ_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
   "role_name": "general_user"
}'

Move user to different tenant:

curl -X PATCH 'https://ai.hatz.ai/v1/admin/users/user_<hashid>' \
-H 'X-API-Key: $HATZ_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
  "tenant_id": "tenant_<hashid>"
}'
Response
{
  "message": "User updated successfully",
  "user_id": "user_<hashid>"
}

© 2025 Hatz AI