/organizations

name: "Huntress Organizations"
description: >
  Huntress organizations as the multi-tenant boundary: org structure, the
  organization key used for agent deployment, full CRUD operations, client
  onboarding and offboarding workflows, and the duplicate-key and
  active-agent deletion errors.
when_to_use: >-
  When creating, listing, updating, or deleting Huntress organizations, or onboarding and
  offboarding a client tenant. Use when: huntress organization, huntress
  org, organization management, create organization, delete organization, client management, or
  multi-tenant.

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