Admin Management - Beta

Admin - Tenant

Manage tenants under your Admin account. View tenant details, usage statistics, and list users within each tenant.

List Tenants

Get all tenants.

Endpoint

GET /v1/admin/tenants

Query Parameters

  • limit (optional): Number of results (1-1000, default: 100)
  • offset (optional): Pagination offset (default: 0)

Example Query 

curl 'https://ai.hatz.ai/v1/admin/tenants?limit=50&offset=0' \
  -H 'X-API-Key: $HATZ_API_KEY'

Response 

[
  {
    "id": "tenant_abc123",
    "name": "Acme Corporation",
    "primary_package_name": "Professional",
    "additional_package_names": ["1500 Extra Credits"],
    "user_count": 25,
    "status": "Active",
    "created_at": "2024-01-15T09:00:00Z",
    "total_credits_used": 15000,
    "total_credit_limit": 50000,
    "tenant_config": {
      "beta_features": false,
      "mfa_required": false,
      "default_model_name": "gpt-4o"
    },
    "disabled_model_names": []
  }
]

Get own MSP

Retrieve details about the internal admin (MSP).

Endpoint

GET /v1/admin/tenants/msp

Example Query 

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

Response 

{
  "name": "Internal Admin MSP",
  "created_at": "2023-01-01T00:00:00Z",
  "primary_package_name": "Enterprise",
  "additional_package_names": [],
  "packages": {},
  "total_credits_used": 125000,
  "total_credit_limit": 500000,
  "admin_user_count": 5,
  "admin_recent_signin_count": 3,
  "admin_login_rate": 0.6,
  "tenant_user_count": 150,
  "tenant_recent_signin_count": 85,
  "tenant_login_rate": 0.57
}

Get Tenant Details

Retrieve details for a specific tenant by ID.

Endpoint

GET /v1/admin/tenants/{tenant_id}

Path Parameters

  • tenant_id: Tenant ID (e.g., "tenant_abc123")

Example Query 

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

Response 

{
  "id": "tenant_abc123",
  "name": "Acme Corporation",
  "primary_package_name": "Professional",
  "additional_package_names": [],
  "user_count": 25,
  "status": "Active",
  "created_at": "2024-01-15T09:00:00Z",
  "total_credits_used": 15000,
  "total_credit_limit": 50000,
  "tenant_config": {
    "beta_features": false,
    "mfa_required": true,
    "default_model_name": "gpt-4o"
  },
  "disabled_model_names": ["claude-3-opus"]
}

Get Tenant Users

Get all users belonging to a specific tenant.

Endpoint

GET /v1/admin/tenants/{tenant_id}/users

Path Parameters

  • tenant_id (required): Tenant ID (e.g., "tenant_abc123")

Query Parameters

  • limit (optional): Number of results (1-1000, default: 100)
  • offset (optional): Pagination offset (default: 0)

Example Request 

curl 'https://ai.hatz.ai/v1/admin/tenants/tenant_abc123/users?limit=50&offset=0' \
  -H 'X-API-Key: $HATZ_API_KEY'

Response 

[
  {
    "id": "user_xyz789",
    "email": "john.doe@acme.com",
    "first_name": "John",
    "last_name": "Doe",
    "tenant_id": "tenant_abc123",
    "role_name": "client_admin",
    "last_sign_in_at": "2024-06-15T14:30:00Z",
    "invitation_status": "Active"
  },
  {
    "id": "user_abc456",
    "email": "jane.smith@acme.com",
    "first_name": "Jane",
    "last_name": "Smith",
    "tenant_id": "tenant_abc123",
    "role_name": "general_user",
    "last_sign_in_at": null,
    "invitation_status": "Provisioned"
  }
]

Create Tenants

Create one or more tenants with optional users.

Endpoint

POST /v1/admin/tenants

Request Body

  • tenants (required): List of tenants to create (1-100, or 1-20 when purchase=true)
    • tenant_name (required): Tenant name (1-255 characters). Must be globally unique across all entities (not MSP-scoped). This is enforced server-side; a request will fail if the name already exists.
    • package_id (optional): Package ID (e.g., "package_xyz"). Required if template_id not provided.
    • template_id (optional): Tenant template ID (e.g., "tentemplate_xyz"). Required if package_id not provided.
    • users (optional): Initial users for the tenant (max 1000 per tenant)
      • email (required): User email address
      • first_name (optional): User first name
      • last_name (optional): User last name
      • role (optional): Default role name (e.g., "general_user", "client_admin")
      • custom_role_name (optional): Custom role slug (e.g., "engineering_lead"). Must be an MSP-wide role since the tenant does not exist yet.
      • role and custom_role_name are mutually exclusive. If neither is provided, the general_user default role is used.
  • purchase (optional): Whether to automatically purchase a license if none are available. Defaults to false. When enabled, the tenants list is capped at 20. **The caller must have billing access on the account to use this option (role of billing manager, admin or primary admin) **
  • send_email (optional): Whether to send invitation emails immediately to created users. Defaults to true. When enabled, the total number of users across all tenants is capped at 1000. Set to false to bypass this limit and provision users without sending emails.

Note -- when purchase is false (default), there must be an existing unassigned package in the account that matches the type specified by the incoming package or template ID in order to create the new tenant and assign a package to them.

Request 

{
  "tenants": [                             // Required: Array of tenants to create (1-100, or 1-20 when purchase=true)
    {
      "tenant_name": "string",             // Required: Tenant name (1-255 characters)
      "package_id": "string",              // Optional: Package ID (e.g., "package_xyz"). Required if template_id not provided
      "template_id": "string",             // Optional: Template ID (e.g., "tentemplate_xyz"). Required if package_id not provided
      "users": [                           // Optional: Array of users
        {
          "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"). Must be MSP-wide.
        }
      ]
    }
  ],
  "purchase": false,                       // Optional: Auto-purchase license if unavailable (default: false, requires billing access)
  "send_email": true                       // Optional: Whether to send invitation emails immediately to created users (default: true)
}

Custom roles on tenant creation: When assigning a custom_role_name to users during tenant creation, the role must be an MSP-wide custom role since the tenant does not exist yet and tenant-scoped roles cannot be referenced. Use GET /v1/admin/roles (without a tenant_id) to list your MSP-wide custom roles and their name slugs.

Example Request 

curl -X POST 'https://ai.hatz.ai/v1/admin/tenants' \
  -H 'X-API-Key: $HATZ_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "tenants": [
      {
        "tenant_name": "Acme Corporation",
        "package_id": "package_abc123",
        "users": [
          {
            "email": "admin@acme.com",
            "first_name": "John",
            "last_name": "Doe",
            "role": "client_admin"
          }
        ]
      }
    ]
  }'

Response 

{
  "message": "Successfully created 1 tenants",
  "total_tenants_created": 1,
  "total_tenants_failed": 0,
  "tenants": [
    {
      "tenant_name": "Acme Corporation",
      "tenant_id": "tenant_def456",
      "success": true,
      "error": null,
      "total_new_users_created": 1,
      "total_new_users_failed": 0,
      "new_users_failed_emails": [],
      "purchase_occurred": false
    }
  ]
}

Update Tenant Configuration

Update tenant configuration settings including beta features, MFA requirements, and default AI model.

Endpoint

PATCH /v1/admin/tenants/{tenant_id}/config

Path Parameters

  • tenant_id (required): Tenant ID (e.g., "tenant_abc123")

Request Body

  • beta_features (optional): Enable or disable beta features
  • mfa_required (optional): Require MFA for all users in tenant
  • default_model_name (optional): Default AI model name (e.g., "gpt-4o"). Set to empty string to clear.

Example Request 

curl -X PATCH 'https://ai.hatz.ai/v1/admin/tenants/tenant_abc123/config' \
  -H 'X-API-Key: $HATZ_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "beta_features": true,
    "mfa_required": true,
    "default_model_name": "gpt-4o"
  }'

Response 

{
  "beta_features": true,
  "mfa_required": true,
  "default_model_name": "gpt-4o"
}

Get Disabled LLMs

Retrieve the list of AI models that are disabled for a specific tenant. Disabled models are unavailable to tenant users in chat and workshop items.

Endpoint

GET /v1/admin/tenants/{tenant_id}/disabled-llms

Path Parameters

  • tenant_id (required): Tenant ID (e.g., "tenant_abc123")

Example Query 

curl 'https://ai.hatz.ai/v1/admin/tenants/tenant_abc123/disabled-llms' \
  -H 'X-API-Key: $HATZ_API_KEY'

Response 

{
  "disabled_model_names": ["claude-3-opus", "gpt-4"]
}

An empty list means all models are enabled for the tenant:

{
  "disabled_model_names": []
}

Update Disabled LLMs

Replace the list of disabled AI models for a tenant. Pass an empty list to enable all models.

Endpoint

PUT /v1/admin/tenants/{tenant_id}/disabled-llms

Path Parameters

  • tenant_id (required): Tenant ID (e.g., "tenant_abc123")

Request Body

  • disabled_model_names (required): List of AI model names to disable. Replaces the existing list entirely.

Example Request 

curl -X PUT 'https://ai.hatz.ai/v1/admin/tenants/tenant_abc123/disabled-llms' \
  -H 'X-API-Key: $HATZ_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "disabled_model_names": ["claude-3-opus", "gpt-4"]
  }'

Response 

{
  "disabled_model_names": ["claude-3-opus", "gpt-4"]
}

Error Responses

  • 400 — One or more model names not found or not enabled

Update Tenant Package

Update the package assigned to a tenant. Accepts a package HashID and schedules the package change.

Endpoint

PUT /v1/admin/tenants/{tenant_id}/package

Path Parameters

  • tenant_id (required): Tenant ID (e.g., "tenant_abc123")

Request Body

  • package_id (required): Package HashID (e.g., "package_abc123")

Example Request 

curl -X PUT 'https://ai.hatz.ai/v1/admin/tenants/tenant_abc123/package' \
  -H 'X-API-Key: $HATZ_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "package_id": "package_xyz789"
  }'

Response 

{
  "message": "Package update scheduled successfully",
  "error": null,
  "scheduled_activation": "2024-07-01T00:00:00Z"
}

Error Responses

  • 400 — Invalid package ID format
  • 403 — Insufficient permissions to access package data
  • 404 — Package could not be found
  • 502 — Error executing update

Bulk Resend Tenant Invitation Emails

Resend invitation emails to all users in a tenant that match a given invitation status. This is useful for bulk-sending invitations to all provisioned users who haven't received an invite yet, or resending to all previously invited users.

Endpoint

POST /v1/admin/tenants/{tenant_id}/resend-invitation-email

Path Parameters

  • tenant_id (required): Tenant ID (e.g., "tenant_abc123")

Request Body 

{
  "status": "string",  // Required: "Invited" or "Provisioned"
  "limit": 1000        // Optional: Max emails to send (1-1000, default: 1000)
}

Invitation statuses:

  • Active — User has signed in at least once.
  • Invited — User was created and sent an invitation email but has not signed in yet.
  • Provisioned — User was created without an invitation email (e.g., send_email was set to false, or the user was SCIM-provisioned).

If there are more matching users than the limit, the response will indicate how many were sent. Call the endpoint again to send to the next batch.

Example Query 

curl -X POST 'https://ai.hatz.ai/v1/admin/tenants/tenant_abc123/resend-invitation-email' \
  -H 'X-API-Key: $HATZ_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "status": "Provisioned"
  }'

Response 

{
  "message": "Successfully sent 5 invitation emails",
  "total_sent": 5,
  "total_failed": 0,
  "failed_emails": []
}
Previous
Admin - User
Next
Admin - Tenant Templates