Checkpoint Avanan API Patterns

Checkpoint Harmony Email API Patterns

Overview

Harmony Email & Collaboration (formerly Avanan) sits alongside Microsoft 365 and Google Workspace via API rather than in the mail path. MSPs use it to review what the detection engines caught, pull the message behind a detection, quarantine or restore mail, and maintain the sender exception lists. Every call in this plugin goes through the Conduit gateway to the Harmony Email Smart API v1.50.

Anti-triggers

• avanan_* tool names — a separate legacy Avanan MCP server serves MSP-partner, tenant and licence management under avanan_* names (avanan_create_tenant, avanan_assign_license). None of them reach quarantine, events or exceptions. This vendor's security surface is hec_* only; if you want tenant or licence administration, that is the legacy server, not this plugin.
• Detection records and their verdicts — use avanan-threats.
• Finding or acting on the message itself — use avanan-quarantine.
• Sender allow/block entries — use avanan-exceptions.
• Another vendor's auth — "client id and secret against a regional gateway" describes most of the email-security stack. Mimecast is mimecast-api-patterns, Proofpoint is proofpoint-api-patterns.

The tool surface

Thirteen tools, all prefixed hec_.

There is no policy surface, no reporting or statistics surface, and no incident object. See Capability gaps.

Events and entities are two id namespaces

This is the distinction that determines every tool choice, and getting it wrong produces a not-found error that reads like a stale id.

• An event is a detection: an engine's verdict, with a type, state, severity and confidence. Its id is eventId.
• An entity is the object that was scanned — usually the email itself, with subject, sender, recipients, attachments and body. Its id is entityId.

They are related but not interchangeable. hec_get_event will not accept an entityId, and hec_quarantine_emails will not accept an eventId. The bridge is the entityId field carried on the event record: read an event, take its entityId, then call hec_get_email to see the message the detection was about.

Both action endpoints exist in parallel for the same reason — hec_quarantine_events posts event ids, hec_quarantine_emails posts entity ids, and they resolve to the same underlying mail action. Use whichever id you already hold rather than converting between them.

Result shape and pagination

Every tool returns the same envelope beneath the formatted text:

{
  "responseEnvelope": {
    "requestId": "…",
    "responseCode": 0,
    "responseText": "…",
    "recordsNumber": 237,
    "scrollId": "…"
  },
  "responseData": [ … ]
}

recordsNumber is the envelope's own count; when it is absent the page length is the only figure available. Do not read it as a page size, and do not report it as a total until the scroll is exhausted.

Pagination is scroll-based, not offset-based. There is no limit, offset, page or sortBy parameter anywhere in the surface. When a result carries a scrollId, pass it back as the scrollId argument on the same tool with the same filters to get the next page; a response with no scrollId is the last page. Changing the filters mid-scroll invalidates the cursor.

Only hec_query_events and hec_search_emails paginate. The exception, action and get-by-id tools return complete results.

Auth, region and scopes

Handled for you by the gateway, but the failure modes surface as tool errors, so the shape matters. Full request detail is in references/http-api.md.

Authentication posts clientId and accessKey — not client_secret — and returns a JWT. Tokens are short-lived (the API reports expiresIn, defaulting to 1800 seconds) and are refreshed transparently.

Region is decoded from the token, not configured. The auth call always goes to the EU host; the returned JWT carries a region claim (eu, us, au, in) that selects the host every subsequent data call uses. A tenant's credentials therefore work from anywhere — you do not pick a region — but a credential whose region claim is wrong sends data calls to a host that holds no data for it.

Scopes are farm:customer pairs, e.g. mt-prod-cp-eu-1:examplecorp. A key may hold one or several. With one scope the API infers it; with several, scopes are injected into the request automatically. A key that returns an empty scope string has no farm association at all and every data call will come back empty — that is a provisioning problem at Checkpoint, not a query problem.

Gotchas

• Empty results are the default failure mode. A wrong region, a scopeless key, or a date range outside retention all return a well-formed response with zero records rather than an error. Before concluding "no threats found", confirm the query returned a non-zero recordsNumber on some broader window.
• Errors carry the vendor's text, not an error code. Failures surface as HEC API error (<status>): <responseText> — the API's own prose from responseEnvelope.responseText. There is no stable machine-readable error code catalogue to switch on; read the text.
• A 401 is as likely to be a region or scope problem as a bad credential. Rotating a working credential is a common wrong response to it.
• Requests time out at 30 seconds. A wide hec_search_emails over a long window can exceed it. Narrow the window rather than retrying identically.
• Every date is ISO 8601 and is interpreted as UTC. Passing a local-time string without an offset silently shifts the window.

Capability gaps

The tool surface is smaller than the Harmony Email console. Nothing here reaches:

• Policies — no tool lists, enables, disables or edits a security policy. Policy work is console-only.
• Incidents — there is no incident object, status, assignee or note. Do not attempt to open, update or close one.
• Reporting — no statistics, trend or aggregation tool. Counts must be derived by paging a query.
• Message bodies and attachment content — hec_get_email returns the entity payload including attachment names, sizes and MD5 hashes, but not the file itself.

Related Skills

• Checkpoint Threats — the event surface
• Checkpoint Quarantine — the entity and action surface
• Checkpoint Exceptions — whitelist and blacklist