Admin Management - Beta

Admin - Tenant Templates

Managing tenant templates within the Hatz platform. Templates allow you to pre-configure settings for new tenants. They do not affect the tenant after the point of creation.

Templates and Custom Roles

Tenant templates are applied when a tenant is created. In the Admin Dashboard, Workspace templates can use an MSP-wide custom role as the default role for new tenants. In the Admin API, use the same role scope deliberately: create the reusable MSP-wide role first, then reference it during tenant creation.

For API-based tenant creation with a custom role that should be reused across many tenants:

  1. Create an MSP-wide custom role with POST /v1/admin/roles/custom by omitting tenant_id.
  2. Use the returned role name slug as custom_role_name when creating tenants with POST /v1/admin/tenants.
  3. Include template_id in the same tenant creation request when you also want to apply a tenant template.

Tenant-scoped custom roles are tied to an existing tenant. They cannot be referenced while creating a brand-new tenant because the tenant does not exist yet. For existing tenants, use the Admin Roles and Admin Users endpoints to duplicate roles, list assignable roles, or update users.

List Tenant Templates

List all tenant creation templates for the current user's managed entity.

Endpoint

GET /v1/admin/tenants/templates

Query Parameters

  • limit (optional): Number of results to return (1-100, default: 50)
  • cursor (optional): Pagination cursor (created_at timestamp from previous response)

Example Request 

curl 'https://ai.hatz.ai/v1/admin/tenants/templates?limit=2' \
  -H 'X-API-Key: $HATZ_API_KEY'

Response 

{
  "templates": [
    {
      "id": "tentemplate_abc123",
      "name": "Standard Business Template",
      "package_name": "Professional",
      "default_model_name": "gpt-4o",
      "beta_features": false,
      "mfa_required": true,
      "created_at": "2024-01-15T09:00:00Z",
      "updated_at": "2024-01-15T09:00:00Z"
    },
    {
      "id": "tentemplate_def456",
      "name": "Enterprise Template",
      "package_name": "Enterprise",
      "default_model_name": "claude-3-5-sonnet",
      "beta_features": true,
      "mfa_required": true,
      "created_at": "2024-01-10T12:00:00Z",
      "updated_at": "2024-01-10T12:00:00Z"
    }
  ],
  "next_cursor": "2024-01-10T12:00:00Z"
}

Pagination Example 

curl 'https://ai.hatz.ai/v1/admin/tenants/templates?limit=20&cursor=2024-01-10T12:00:00Z' \
  -H 'X-API-Key: $HATZ_API_KEY'

Get Tenant Creation Template

Get a specific tenant creation template by ID.

Endpoint

GET /v1/admin/tenants/templates/{template_id}

Path Parameters

  • template_id (required): Template ID (e.g., "tentemplate_abc123")

Example Request 

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

Response 

{
  "id": "tentemplate_abc123",
  "name": "Standard Business Template",
  "package_name": "Professional",
  "default_model_name": "gpt-4o",
  "beta_features": false,
  "mfa_required": true,
  "created_at": "2024-01-15T09:00:00Z",
  "updated_at": "2024-01-15T09:00:00Z"
}

Create Tenant Creation Template

Create a new tenant creation template.

Endpoint

POST /v1/admin/tenants/templates

Request Body

  • name (required): Template name (3-255 characters)
  • package_name (required): Package name to assign to tenants created with this template. Must be one of Intro, Starter, SMB, Business, or Professional that corresponds with packages available.
  • default_model_name (optional): Default AI model name (e.g., "gpt-4o")
  • beta_features (optional): Enable beta features for tenants (default: false)
  • mfa_required (optional): Require MFA for tenants (default: false)

Request 

{
  "name": "string",              // Required: Template name (3-255 characters)
  "package_name": "string",      // Required: Intro, Starter, SMB, Business, or Professional.
  "default_model_name": "string", // Optional: Default AI model (e.g., "gpt-4o")
  "beta_features": boolean,      // Optional: Enable beta features (default: false)
  "mfa_required": boolean        // Optional: Require MFA (default: false)
}

Example Request 

curl -X POST 'https://ai.hatz.ai/v1/admin/tenants/templates' \
  -H 'X-API-Key: $HATZ_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Standard Business Template",
    "package_name": "Professional",
    "default_model_name": "gpt-4o",
    "beta_features": false,
    "mfa_required": true
  }'

Response 

{
  "id": "tentemplate_abc123",
  "name": "Standard Business Template",
  "package_name": "Professional",
  "default_model_name": "gpt-4o",
  "beta_features": false,
  "mfa_required": true,
  "created_at": "2024-01-15T09:00:00Z",
  "updated_at": "2024-01-15T09:00:00Z"
}

Update Tenant Creation Template

Update an existing tenant creation template. Only provided fields will be updated.

Endpoint

PUT /v1/admin/tenants/templates/{template_id}

Path Parameters

  • template_id (required): Template ID (e.g., "tentemplate_abc123")

Request Body

  • name (optional): Template name (3-255 characters)
  • package_name (optional): Package name
  • default_model_name (optional): Default AI model name. Set to empty string to clear.
  • beta_features (optional): Enable beta features
  • mfa_required (optional): Require MFA

Example Request 

curl -X PUT 'https://ai.hatz.ai/v1/admin/tenants/templates/tentemplate_abc123' \
  -H 'X-API-Key: $HATZ_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Updated Business Template",
    "mfa_required": true
  }'

Response 

{
  "id": "tentemplate_abc123",
  "name": "Updated Business Template",
  "package_name": "Professional",
  "default_model_name": "gpt-4o",
  "beta_features": false,
  "mfa_required": true,
  "created_at": "2024-01-15T09:00:00Z",
  "updated_at": "2024-01-16T10:30:00Z"
}

Example: Clear Default Model 

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

Delete Tenant Creation Template

Delete a tenant creation template.

Endpoint

DELETE /v1/admin/tenants/templates/{template_id}

Path Parameters

  • template_id (required): Template ID (e.g., "tentemplate_abc123")

Example Request 

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

Response

Returns

204 No Content

on success.

Error Responses

All endpoints may return the following error responses:

400 Bad Request 

{
  "detail": "Invalid template ID: Must use template ID format (tentemplate_xxxxx)"
}

{
  "detail": "AI model 'invalid-model' not found or not enabled"
}

{
  "detail": "No fields to update"
}

404 Not Found 

{
  "detail": "Template not found"
}

{
  "detail": "Template not found or insufficient permissions"
}

422 Validation Error 

{
  "detail": [
    {
      "loc": ["body", "name"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}
Previous
Admin - Machine Collections Beta
Next
Admin - Package