Tenants

Tenants represent client organisations managed within your HomeBase instance. Each tenant is an isolated unit with its own users, devices, alerts, and compliance posture.

The tenant object

json

{
  "id": "ten_01hxyz",
  "name": "Acme Corp",
  "slug": "acme-corp",
  "status": "active",
  "region": "ap-southeast-2",
  "plan": "enterprise",
  "contact_email": "[email protected]",
  "created_at": "2025-01-15T09:00:00Z",
  "updated_at": "2025-06-01T14:22:00Z",
  "metadata": {}
}

List tenants

bash

GET /v1/tenants

Name	Type	Required	Description
page	integer	No	Page number (default: 1).
per_page	integer	No	Results per page, max 100 (default: 20).
filter[status]	string	No	Filter by status: active, suspended, offboarded.
filter[plan]	string	No	Filter by plan tier.

Get a tenant

bash

GET /v1/tenants/:id

bash

curl https://api.hldgroup.org/v1/tenants/ten_01hxyz \
  -H "Authorization: Bearer hld_live_xxxx"

Create a tenant

bash

POST /v1/tenants

Name	Type	Required	Description
name	string	Yes	Display name of the organisation.
contact_email	string	Yes	Primary contact email.
region	string	Yes	Data residency region: ap-southeast-2, us-east-1, eu-west-1.
plan	string	No	Plan tier: starter, professional, enterprise. Defaults to starter.
metadata	object	No	Arbitrary key-value pairs for your own use.

bash

curl -X POST https://api.hldgroup.org/v1/tenants \
  -H "Authorization: Bearer hld_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corp",
    "contact_email": "[email protected]",
    "region": "ap-southeast-2",
    "plan": "enterprise"
  }'

Update a tenant

bash

PATCH /v1/tenants/:id

Accepts the same fields as create. Only provided fields are updated (partial update).

Suspend / reactivate

bash

POST /v1/tenants/:id/suspend
POST /v1/tenants/:id/reactivate

Warning:Suspending a tenant immediately halts all active monitoring and response for that organisation. Reactivation resumes full coverage within 60 seconds.

Alerts & threats Devices