Freshdesk package v1.0.0

A Freshdesk API key used as HTTP Basic credentials, held in the client's own secret manager. Freshdesk's documentation authenticates with the API key as the Basic-auth username and any single character (conventionally 'X') as the password ('curl -u apikey:X'), so the stored material must be the complete Authorization header value: the scheme 'Basic', one separating space, then the Base64 encoding of '{api_key}:X' — 'Basic <base64>'.

Key issuance is an external process: each agent finds or regenerates their own API key in their Freshdesk profile settings; the executor performs no credential lifecycle itself and injects the stored value verbatim.

Least privilege: an API key authenticates AS that agent and inherits the agent's full role permissions, so issue the key from a dedicated least-privilege service-account agent whose role covers exactly the registered capabilities (read tickets, contacts and agents; reply and note on tickets) and nothing more.

Expiry and revocation: API keys do not expire on their own; regenerating the key in profile settings invalidates the previous key immediately, and deleting or deactivating the agent disables its key. Because the key is the credential (no separate tokens are issued from it), regeneration is full revocation of this value — no already-issued tokens survive it, because none exist. Review the owning agent's role and the account's key inventory before enabling.

Executor hygiene: the value must live only in executor memory for the lifetime of a call, must never be written to logs, traces or diagnostics, and must not appear in crash dumps; a deployment that cannot meet that bar must not enable the pack.

The endpoint host 'your-domain.freshdesk.invalid' is a reserved non-production placeholder (.invalid is an RFC 2606 reserved TLD that can never resolve): substitute the account's own Freshdesk domain (your-domain.freshdesk.com — the account's Freshdesk domain; this review did not find Freshdesk API documentation supporting a custom support URL as an interchangeable API destination, so none is offered) before enabling, in the endpoints, the resource locators and the egress allowlist — the allowlist matches exactly, so all three must be substituted together, and substitution is a required pre-enablement step.

Note that allowlisting the reserved placeholder host does not make an unsubstituted pack safe: an unsubstituted pack has never been bound to the account it claims to govern, and its review says nothing about that account. This pack registers only endpoints the official Freshdesk API documentation (developers.freshdesk.com/api) lists: the tickets, contacts and agents collection reads, and creating a reply or a note on a ticket.

All read capabilities cover the collection read only: single-record reads (GET /api/v2/tickets/[id], /api/v2/contacts/[id], /api/v2/agents/[id]), search and filter endpoints (/api/v2/search/...), autocomplete, and ticket sub-resource listings (conversations, time_entries, watchers, accesses) are not registered by this pack — separate navigation and sub-resource endpoints are not registered unless named. Consequential effects: a Freshdesk reply is the public, customer-facing response on a ticket — it is delivered to the requester on the ticket's channel (typically email), so reply creation declares send at the minimum R3 tier alongside create.

Note creation is judged by the same effect rule: Freshdesk documents notes as private by default, but the same endpoint accepts private=false (a public note the requester can see) and a notify_emails array (email addresses of agents or users 'who need to be notified about this note') — the unrestricted effect of the endpoint includes transmitting to people, so note creation also declares send at the minimum R3 tier. Send is one of the designated actions requiring human approval: a delivered reply or notification cannot be recalled after delivery.

A private-note-only variant is not registered as R2: the private flag and notify_emails are request-body properties of the same endpoint, and a pack registers an endpoint, not a body value, so nothing in the registration would enforce the restriction.

Documented exclusions: this pack does not register ticket create or update (a created ticket can email the requester and would likewise carry send), outbound email tickets (/api/v2/tickets/outbound_email), forward and reply_to_forward, ticket delete/restore, merge, bulk update, canned responses, contact create/update/delete or merge, agent create/update/delete, and the outbound-messages channel API.

Data-class rationale: tickets and contacts identify individuals and carry their correspondence, so both are pii; agents are the helpdesk's own staff directory (names, emails, roles) and are registered pii — staff names and email addresses are personal data whether they identify employees or customers.

The endpoints are verified against the provider documents named in the review block, and the credential-custody review was completed on 2026-09-21 against this pack's custody model (an agent's API key used as HTTP Basic credentials, held in the customer's vault), with these findings, one per gated property.

Issuance authority and delegation: each agent finds or regenerates their own API key in their Freshdesk profile settings, so issuance authority sits with the account's own agents and admins; the key authenticates AS that agent and delegates the agent's full role permissions to every call. Scope: Freshdesk documents no per-key scoping — the key inherits the agent's role permissions, so least privilege is achieved by issuing the key from a dedicated service-account agent whose role covers exactly the registered capabilities and nothing more.

Audience: no audience mechanism is documented — the Basic credential authorizes against the account's freshdesk.com domain, and audience binding beyond that is not established. TTL: API keys do not expire on their own and stay live until regenerated or revoked.

Refresh ownership: there is no refresh — the key is the credential and no tokens are derived from it; re-issuance is an external administrative action, and the executor injects the stored value verbatim and performs no credential lifecycle itself.

Revocation: regenerating the key in profile settings invalidates the previous key immediately, and deleting or deactivating the agent disables its key; because no derived tokens exist, regeneration is full revocation of this value. Executor access and replay/exposure: the executor reads only the vault reference; the credential is replayable with no TTL bound until regenerated, so the vault reference is the only place the value may live.

Alternate access paths: the Freshdesk web UI, other agents' keys and other integrations retain access outside this pack, and regenerating or deleting this key closes only this path. The credential review is complete. Assign accountable owners before deployment.