Skip to main content
The Huntress Managed Security Awareness Training integration imports two metrics from your Huntress SAT account into Regentra:
  • Workforce-coverage rate — the share of active learners who finished training in the rolling 365-day window.
  • Phishing-simulation rates — the rolling 90-day compromise rate and report rate across completed campaigns.
Both metrics are stored as MonitoringSignal evidence rows and surface on the relevant control cards in Compliance → Controls.

​
What syncs

SignalWindowMapped controls
Workforce-coverage rateRolling 365 daysSecurity reminders, workforce privacy training
Phishing compromise + report ratesRolling 90 days (completed campaigns only)Security reminders, workforce privacy training, incident response and reporting
The phishing report rate is the operational evidence that personnel are reporting suspected security events through the proper channel — it maps to the incident-reporting control, not to anti-malware tooling.
Per-learner records, learner emails, and assignment names are not persisted in Regentra. Only the aggregate counts that drive the rate calculations are stored, so the integration never copies workforce PII out of Huntress.

​
Required OAuth scopes

The Huntress API Client must grant exactly these five read-only scopes. If any is missing, the token call returns invalid_scope and Regentra flags the credential as auth_failed until you reissue it.
ScopeWhat it unlocks in Regentra
account:readAccount name, plan, and the activeLearners count used as the workforce denominator
assignments:readLists in-progress and completed assignments (training catalog discovery)
assignments:learner-activityPer-learner activity records — the numerator for the coverage calculation
learners:readLearner records used to deduplicate completions across multiple assignments
phishing-campaigns:readCampaign aggregates: attemptStats.sent, compromised, reported
Regentra does not request write scopes. The API Client cannot create assignments, modify learners, or launch campaigns from your side.

​
Setup

The full step-by-step lives inline on the Huntress SAT card in Settings → Integrations. The short version:
1

Enable API access on your account

Email support@huntress.com and ask them to enable API access for your tenant. This is a one-time provisioning step that typically takes about one business day.
2

Create the API Client

In Huntress → Settings → API Clients → Create Client, choose Client Credentials as the grant type, and grant the five read-only scopes listed above.
3

Paste credentials into Regentra

On the Huntress SAT card, paste the Client ID and Client Secret. Leave Account ID blank unless the API Client has access to multiple accounts — Regentra auto-detects the account when there is exactly one.
4

Test before Save

Click Test Connection before Save. A green result confirms the OAuth token works and the account is visible. After Save, click Sync Now to pull the first round of evidence.

​
Account ID auto-detect

When you leave the Account ID field blank, Regentra calls /accounts at test/sync time and behaves as follows:
Visible accountsBehavior
Exactly oneUse it, backfill the credential row, all future syncs use the stored ID directly
ZeroHard error — the API Client is provisioned but no accounts are attached. Re-open the support ticket.
Two or moreHard error listing the available IDs. Paste one into the Account ID field and save again.
If you typed an Account ID at save time, Regentra validates it precisely on every sync — a 404 means the ID is wrong, an account was removed, or the API Client lost access.

​
How the metrics are calculated

​
Workforce-coverage rate

coverage = round(distinctTrainedLearners / activeLearners × 100)
  • Numerator (distinctTrainedLearners) — the count of unique learner IDs whose completedAt timestamp falls in the last 365 days across any assignment. A learner who completed three assignments in the window is counted once.
  • Denominator (activeLearners) — meta.counts.activeLearners on the /accounts/{id} response. This is Huntress’s authoritative workforce size.
ResultStatus
coverage ≥ 90%Pass
70% ≤ coverage < 90%Warning
coverage < 70%Fail
activeLearners == 0Warning (no workforce to measure)

​
Phishing compromise + report rates

Only campaigns with status: "completed" ending in the last 90 days are included. Campaigns with attemptStats.sent == 0 are skipped to avoid zero-effort tests inflating the denominator. 
compromiseRate = round(sum(compromised) / sum(sent) × 100)
reportRate     = round(sum(reported)    / sum(sent) × 100)
ResultStatus
compromiseRate ≤ 5%Pass
5% < compromiseRate ≤ 15%Warning
compromiseRate > 15%Fail
sum(sent) == 0Warning (no recent campaigns)
Report rate is recorded alongside compromise rate for evidence completeness but does not drive the pass/warning/fail status — the compromise rate is the primary signal because it measures harm risk directly, while report rate measures the secondary reporting behavior.

​
Sync schedule

  • Automatic: daily at 7:00 AM Eastern Time (cron TZ=America/New_York 0 7 * * *)
  • Manual: the Sync Now button on the card queues an immediate run that returns within a minute or two
Manual and scheduled syncs are serialized per organization, so clicking Sync Now during a scheduled run waits for the current run to finish rather than racing it.

​
Auth failure backoff

If a sync run fails for an auth reason — bad credentials, missing scopes, revoked Client — Regentra flags the credential as auth_failed and skips it on subsequent scheduled runs for 24 hours. This stops the daily cron from burning Huntress API budget on a known-broken credential. After 24 hours, the credential is retried automatically, so rotating an API Client clears the backoff on the next scheduled tick (or sooner if you click Sync Now). Auth failures include 401 Unauthorized, invalid_client, invalid_grant, and missing-scope errors. Any other failure (e.g. a single assignment 404’ing mid-sync) does not trigger the backoff — those propagate as a regular error status and retry on the next tick.

​
Rate-limit budget

Huntress documents two limits per organization (not per token):
  • 1,500 requests/hour sustained
  • 200 requests/minute burst
A daily sync for a 500-learner tenant typically uses 20–40 requests, so the budget is not a concern in practice. Regentra logs a warning to the audit trail when X-RateLimit-Remaining drops below 100 — if you see that warning, check whether another integration or a custom script is sharing the same Client.

​
Pagination caps

Regentra caps each endpoint to prevent runaway syncs on very large tenants:
EndpointCapWhat happens at the cap
/accounts/{id}/assignments5,000The sync truncates with truncated: true in metadata
/assignments/{id}/learner-activity1,000 per assignmentPer-assignment truncation, sync continues
/accounts/{id}/phishing-campaigns5,000The sync truncates with truncated: true in metadata
If a sync run truncates, the evidence row records the flag so auditors can see the coverage rate is computed against a partial denominator. Contact support if your tenant routinely truncates — we adjust the caps per-org rather than rolling them out globally.

​
Security model

  • Transport — all calls are HTTPS-only against mycurricula.com. Regentra refuses non-HTTPS URLs and rejects any hostname not on the allowlist, which prevents a corrupted credential from redirecting traffic.
  • Token storage — the Client Secret is encrypted at rest with AES-256-GCM using an org/provider/column-bound additional authenticated data (AAD) value, so a database write attack cannot lift one tenant’s secret into another tenant’s row.
  • Token lifetime — access tokens are fetched fresh on every sync run (typically once a day) and are not cached, so a leaked token has at most a single sync run of useful lifetime.
  • OAuth fallback — Regentra first tries HTTP Basic Authentication for the token call (Authorization: Basic <base64>) and falls back to credentials-in-body only if the server rejects Basic with 401 invalid_client or 405 method_not_allowed. New Huntress API Clients accept Basic.

​
Troubleshooting

The API Client was created with fewer than five scopes. Open it in Huntress, add the missing scopes, and click Test Connection again. You do not need to issue a new client.
The API Client was provisioned but is not attached to any account. This usually means support enabled API access but skipped the attach step. Reply to the support thread asking them to attach the API Client to your account.
Your Client has access to more than one account (common for MSP parents). Copy one of the listed account IDs, paste it into the Account ID field, and Test again.
The Client Secret was probably rotated in Huntress and the old value is still in Regentra. Paste the new secret, Test, then Save. The 24-hour backoff clears on the next successful sync.
The denominator is Huntress’s activeLearners count — verify that in Huntress under Settings → Account. If it is correct, the most common cause is that learners completed assignments more than 365 days ago and have not retaken anything since; Regentra’s window is rolling 365 days, not “ever”.
No campaigns ended in the last 90 days, or every recent campaign had sent == 0. Launch a campaign in Huntress and run Sync Now after it completes.
Your tenant exceeded the per-endpoint cap (5,000 assignments or 5,000 campaigns). The metrics still compute against the truncated page, but the denominator is partial. Contact support so we can adjust the cap for your org.