Huntress Organizations

Huntress Organizations

Overview

Organizations in Huntress represent MSP client tenants. Each organization contains agents, incidents, and escalations scoped to that client. This skill covers full CRUD operations for organizations and MSP multi-tenant management patterns.

Key Concepts

Organization Structure

Organizations are the primary tenant boundary in Huntress. Agents, incidents, escalations, and billing are all scoped to organizations.

Organization Keys

Each organization has a unique key used during agent installation to associate endpoints with the correct client.

API Patterns

List Organizations

huntress_organizations_list

Parameters:

• page_token — Pagination token

Example response:

{
  "organizations": [
    {
      "id": "org-456",
      "name": "Acme Corporation",
      "key": "acme_corp",
      "agent_count": 150,
      "created_at": "2024-01-15T10:00:00Z"
    }
  ],
  "next_page_token": "eyJwYWdlIjoyfQ=="
}

Get Organization

huntress_organizations_get

Parameters:

• organization_id — The organization ID

Create Organization

huntress_organizations_create

Parameters:

• name — Organization display name
• key — Unique organization key (used in agent install)

Example request:

{
  "name": "New Client Inc",
  "key": "new_client_inc"
}

Update Organization

huntress_organizations_update

Parameters:

• organization_id — The organization ID
• name — Updated name

Delete Organization

huntress_organizations_delete

Parameters:

• organization_id — The organization to delete

WARNING: Deleting an organization removes all associated agents and data. This action is irreversible.

Common Workflows

Client Onboarding

1. Create organization with huntress_organizations_create
2. Note the organization key for agent deployment
3. Deploy agents to client endpoints using the org key
4. Verify agents appear with huntress_agents_list filtered by org

Client Offboarding

1. List agents for the organization
2. Confirm all agents will be removed
3. Delete the organization with huntress_organizations_delete
4. Verify cleanup is complete

Organization Audit

1. List all organizations with huntress_organizations_list
2. For each, check agent count and last activity
3. Identify organizations with zero agents (potential cleanup)
4. Cross-reference with PSA/RMM client lists

Error Handling

Duplicate Key

Cause: Organization key already exists Solution: Use a unique key; check existing organizations first

Organization Not Found

Cause: Invalid organization ID Solution: List organizations to verify the correct ID

Cannot Delete Organization with Active Agents

Cause: Organization still has agents reporting Solution: Uninstall agents before deleting the organization

Best Practices

• Use consistent naming conventions for organization keys
• Match organization names to PSA/RMM client names for easy cross-reference
• Audit organizations periodically for stale or empty tenants
• Document the organization key used for each client's agent deployment
• Never delete organizations without confirming agent removal first

Related Skills

• [api-patterns](../api-patterns/SKILL.md) - Authentication and pagination
• [agents](../agents/SKILL.md) - Agents within organizations
• [incidents](../incidents/SKILL.md) - Incidents scoped to organizations
• [billing](../billing/SKILL.md) - Billing per organization