Admin Management - Beta

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. By default, 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. Set send_email to false to provision users without sending invitation emails immediately.

Tenant User Roles

When inviting users to a tenant, you can assign them a role 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 Body 

{
  "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: Default role name (e.g., "general_user")
      "custom_role_name": "string"   // Optional: Custom role slug (e.g., "engineering_lead")
    }
  ],
  "send_email": true               // Optional: Whether to send invitation emails immediately (default: true)
}

Role assignment: Provide either role (for default roles like general_user, client_admin) or custom_role_name (for custom roles like engineering_lead), but not both. If neither is provided, the user is assigned the general_user default role. Use GET /v1/admin/tenants/{tenant_id}/roles to list assignable roles and their name slugs.

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 MSP Users

Invite users to the MSP. The tenant is automatically resolved from the authenticated user's managed entity -- you do not need to provide a tenant_id. Set send_email to false to provision users without sending invitation emails immediately.

Admin-Level (MSP) User Roles

When inviting users to the MSP, you can assign them a role 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/msp

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 role name (e.g., "helpdesk")
      "custom_role_name": "string"   // Optional: Custom role slug (e.g., "engineering_lead")
    }
  ],
  "send_email": true               // Optional: Whether to send invitation emails immediately (default: true)
}

Role assignment: Provide either role (for default MSP roles like helpdesk, admin) or custom_role_name (for custom roles like engineering_lead), but not both. If neither is provided, the user is assigned the helpdesk default role. Use GET /v1/admin/tenants/{tenant_id}/roles to list assignable roles and their name slugs.

Example Query 

curl 'https://ai.hatz.ai/v1/admin/users/invite/msp' \
  -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

Query Parameters

  • email (required): User email address to search for

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_abc123",
  "email": "user@example.com",
  "first_name": "First",
  "last_name": "Last",
  "tenant_id": "tenant_cdg123",
  "role_name": "general_user",
  "last_sign_in_at": "2024-12-01T10:30:00Z",
  "invitation_status": "Active"
}

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_abc123")

Example Query 

curl 'https://ai.hatz.ai/v1/admin/users/user_abc123' \
  -H 'X-API-Key: $HATZ_API_KEY'

Response 

{
  "id": "user_abc123",
  "email": "user@example.com",
  "first_name": "First",
  "last_name": "Last",
  "tenant_id": "tenant_cdg123",
  "role_name": "general_user",
  "last_sign_in_at": "2024-12-01T10:30:00Z",
  "invitation_status": "Active"
}

Delete User

Remove a user from their tenant.

Endpoint

DELETE /v1/admin/users/{user_id}

Path Parameters

  • user_id: User ID to delete (e.g., "user_abc123")

Example Query 

curl -X DELETE 'https://ai.hatz.ai/v1/admin/users/user_abc123' \
  -H 'X-API-Key: $HATZ_API_KEY'

Response 

{
  "message": "User deleted successfully",
  "user_id": "user_abc123"
}

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 MSP's account.

Endpoint

PATCH /v1/admin/users/{user_id}

Path Parameters

  • user_id: User ID to update (e.g., "user_abc123")

Request Body 

{
  "first_name": "string",         // Optional: Update first name
  "last_name": "string",          // Optional: Update last name
  "role_name": "string",          // Optional: Default role name (e.g., "general_user")
  "custom_role_name": "string",   // Optional: Custom role slug (e.g., "engineering_lead")
  "tenant_id": "string"           // Optional: Move user to this tenant (id)
}

Role update: Provide either role_name (for default roles like general_user, client_admin) or custom_role_name (for custom roles like engineering_lead), but not both. At least one field must be provided. All fields are optional - provide only the fields you want to update.

Tenant move: When moving a user to a different tenant via tenant_id, the user's role is automatically reset to general_user. To assign a different role on the new tenant, include role_name or custom_role_name in the same request.

Example Queries

Update name:

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

Change to a default role:

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

Change to a custom role:

curl -X PATCH 'https://ai.hatz.ai/v1/admin/users/user_abc123' \
  -H 'X-API-Key: $HATZ_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "custom_role_name": "engineering_lead"
  }'

Move user to different tenant:

curl -X PATCH 'https://ai.hatz.ai/v1/admin/users/user_abc123' \
  -H 'X-API-Key: $HATZ_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "tenant_id": "tenant_cdg123"
  }'

Response 

{
  "message": "User updated successfully",
  "user_id": "user_abc123"
}

Bulk Update User Roles

Update the role of multiple users to a single role in one request. The role is resolved once and applied to all specified users concurrently.

Endpoint

PATCH /v1/admin/users/roles

Request Body 

{
  "user_ids": ["user_abc123", "user_def456"],  // Required: User HashIDs (1-1000, no duplicates)
  "role_name": "string",                       // Optional: Default role name (e.g., "general_user")
  "custom_role_name": "string"                 // Optional: Custom role slug (e.g., "engineering_lead")
}

Role assignment: Exactly one of role_name or custom_role_name must be provided. They are mutually exclusive.

Example Query 

curl -X PATCH 'https://ai.hatz.ai/v1/admin/users/roles' \
  -H 'X-API-Key: $HATZ_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "user_ids": ["user_abc123", "user_def456", "user_ghi789"],
    "role_name": "client_admin"
  }'

Response 

{
  "message": "Successfully updated roles for 3 user(s)",
  "total_updated": 3,
  "total_failed": 0,
  "results": [
    { "user_id": "user_abc123", "success": true, "error": null },
    { "user_id": "user_def456", "success": true, "error": null },
    { "user_id": "user_ghi789", "success": true, "error": null }
  ]
}

Resend Invitation Emails

Resend invitation emails to specific users by their user ID or email address. Useful for users whose invitation has expired or who did not receive the original email.

Endpoint

POST /v1/admin/users/resend-invitation-email

Request Body 

{
  "user_ids": ["user_abc123"],   // Optional: List of user HashIDs (max 1000)
  "emails": ["user@example.com"] // Optional: List of email addresses (max 1000)
}

Note: At least one of user_ids or emails must be provided. Both can be provided in the same request. Each list accepts up to 1000 entries.

Example Query 

curl -X POST 'https://ai.hatz.ai/v1/admin/users/resend-invitation-email' \
  -H 'X-API-Key: $HATZ_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "user_ids": ["user_abc123"],
    "emails": ["user@example.com"]
  }'

Response 

{
  "message": "Successfully sent 2 invitation emails",
  "total_sent": 2,
  "total_failed": 0,
  "failed_emails": []
}
Previous
Usage Analytics
Next
Admin - Tenant