Huntress User Management API Guide

Auth method: HTTP Basic Auth using Account API key as username and password (or Bearer token in some contexts); API keys generated per account in the Huntress portal

Setup steps

1. Log in to the Huntress portal at app.huntress.io
2. Navigate to Account Settings > API Keys
3. Click 'Generate API Key' and copy the key and secret
4. Use the key as the username and secret as the password in HTTP Basic Auth headers, e.g., Authorization: Basic base64(key:secret)

List Organizations (Accounts)

• Method: GET
• URL: https://api.huntress.io/v1/organizations
• Watch out for: Huntress uses 'organizations' to refer to managed accounts/tenants, not end-users. User management is scoped under accounts.

Request example

GET /v1/organizations?limit=25&page=1
Authorization: Basic <base64(key:secret)>

Response example

{
  "organizations": [
    {"id": 123, "name": "Acme Corp", "created_at": "2023-01-01T00:00:00Z"}
  ],
  "pagination": {"current_page": 1, "total_pages": 4}
}

Get Organization

• Method: GET
• URL: https://api.huntress.io/v1/organizations/{id}
• Watch out for: Requires the numeric organization ID, not name.

Request example

GET /v1/organizations/123
Authorization: Basic <base64(key:secret)>

Response example

{
  "organization": {
    "id": 123,
    "name": "Acme Corp",
    "created_at": "2023-01-01T00:00:00Z"
  }
}

List Agents (Endpoints)

• Method: GET
• URL: https://api.huntress.io/v1/agents
• Watch out for: Agents represent monitored endpoints/devices, not portal users. Filter by organization_id to scope results.

Request example

GET /v1/agents?organization_id=123&limit=25
Authorization: Basic <base64(key:secret)>

Response example

{
  "agents": [
    {"id": 456, "hostname": "DESKTOP-ABC", "platform": "windows"}
  ]
}

List Reports (Incident Reports)

• Method: GET
• URL: https://api.huntress.io/v1/reports
• Watch out for: Reports are security incident reports, not user activity logs.

Request example

GET /v1/reports?organization_id=123
Authorization: Basic <base64(key:secret)>

Response example

{
  "reports": [
    {"id": 789, "status": "open", "created_at": "2024-01-15T10:00:00Z"}
  ]
}

Get Account Info

• Method: GET
• URL: https://api.huntress.io/v1/account
• Watch out for: Returns the top-level account associated with the API key, not individual portal users.

Request example

GET /v1/account
Authorization: Basic <base64(key:secret)>

Response example

{
  "account": {
    "id": 1,
    "name": "My MSP Account",
    "created_at": "2022-06-01T00:00:00Z"
  }
}

• Rate limits: Huntress enforces rate limiting on API requests; specific numeric limits are not publicly documented in official sources as of the research date

• Rate-limit headers: Unknown

• Retry-After header: Unknown

• Rate-limit notes: Official docs do not explicitly publish per-plan rate limit numbers or rate-limit response headers. Contact Huntress support for current limits.

• Pagination method: offset

• Default page size: 25

• Max page size: 500

• Pagination pointer: page and limit query parameters (e.g., ?page=1&limit=25)

• Webhooks available: No

• Webhook notes: Huntress does not publicly document a webhook system for user-management events as of the research date. Incident and detection notifications are delivered via email or integrations (e.g., PSA tools).

• Alternative event strategy: Poll the /v1/reports and /v1/agents endpoints for changes, or use PSA/ticketing integrations (ConnectWise, Autotask) for event-driven workflows.

• SCIM available: No
• SCIM version: Not documented
• Plan required: N/A
• Endpoint: Not documented

Limitations:

• Huntress does not offer a native SCIM 2.0 endpoint for automated user provisioning/deprovisioning as of the research date.
• No IdP (Okta, Entra ID, Google Workspace, OneLogin) SCIM connectors are officially documented.

Three primary automation scenarios are well-supported by the current API surface.

First, enumerating all managed organizations and their endpoints: GET /v1/organizations?limit=500 returns child orgs, then GET /v1/agents?organization_id={id}&limit=500 scopes endpoints per org - iterate pages when total_pages exceeds 1.

Second, pulling open incident reports for a specific org: GET /v1/reports?organization_id={id}&status=open returns open incidents;

paginate with ?page=2 as needed, and confirm status filter values against the live API docs as they may change across versions.

Third, syncing the Huntress organization list into an external CMDB or ticketing system: poll GET /v1/organizations?limit=500 on a schedule, diff against stored IDs to detect additions or removals, and use org IDs as the correlation key for subsequent agent and report calls.

Note that there are no webhooks for any of these events polling is the only supported pattern, and numeric rate limits are not publicly documented, so polling frequency should be tuned conservatively.

Enumerate all managed organizations and their agents

1. Authenticate with HTTP Basic Auth using your account API key and secret.
2. GET /v1/organizations?limit=500 to retrieve all child organizations.
3. For each organization ID, GET /v1/agents?organization_id={id}&limit=500 to list monitored endpoints.
4. Handle pagination via the 'pagination.total_pages' field in the response.

Watch out for: If you have more than 500 organizations, you must iterate through pages. The max limit per request is 500.

Pull open incident reports for a specific organization

1. Authenticate with HTTP Basic Auth.
2. GET /v1/reports?organization_id={id}&status=open to retrieve open incident reports.
3. Parse the response array for report IDs, severity, and timestamps.
4. Paginate using ?page=2 if total_pages > 1.

Watch out for: Report status filter values should be confirmed against the official API docs as they may change between API versions.

Sync Huntress organization list into an external CMDB or ticketing system

1. Authenticate with HTTP Basic Auth.
2. GET /v1/organizations?limit=500 and store organization IDs and names.
3. Periodically re-run the request and diff against stored data to detect new or removed organizations.
4. Use organization IDs to correlate with agents and reports in subsequent API calls.

Watch out for: There are no webhooks to notify of new organization creation; polling is required. Polling frequency should be tuned to avoid undocumented rate limits.

The most significant caveat for automation engineers: there is no publicly documented REST endpoint to create, update, or delete portal user accounts (human users) via the API. User lifecycle management is UI-only.

Additionally, SCIM 2.0 is not available, meaning no IdP connector (Okta, Entra ID, Google Workspace, OneLogin) can automate provisioning or deprovisioning against the Huntress identity graph. The API is purpose-built for MSP management of organizations and endpoints - not for managing the human operators who log into the portal.

Any integration that assumes user provisioning parity with the portal will need a manual fallback layer.