Intercom package v1.0.0

An Intercom access token (bearerAuth in the REST API reference), held in the client's own secret manager. The stored material must be the complete Authorization header value: the scheme 'Bearer', one separating space, then the token — 'Bearer <token>'. Token issuance is an external process: a workspace admin creates an app in the Intercom Developer Hub, and the workspace's access token is issued from the app's Authentication section; the executor performs no token lifecycle itself and injects the stored value verbatim.

Least privilege: build the app for the exact registered surface — read access to contacts, companies and conversations, plus conversation reply — and no other permission; Intercom scopes app permissions per resource in the Developer Hub.

Expiry and revocation: Intercom access tokens do not expire on their own; the token is revoked by deleting or rotating it in the Developer Hub (or by uninstalling the app), and a revoked value fails closed. Because the token is the credential (no separate tokens are issued from it), deletion revokes exactly this value. Review the workspace's app inventory and token age 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.

Every endpoint here is on api.intercom.io, the shared Intercom production API host named in Intercom's REST API reference, so there is no per-customer host to substitute. Intercom also operates regional hosts (api.eu.intercom.io, api.au.intercom.io); a deployment whose workspace lives in a regional data host must substitute that host in the endpoints, resource locators and egress allowlists — the allowlist matches exactly, so all three move together.

Callers must send the Intercom-Version header (the reference documents version 2.16 as current); the version is a request header, not part of the registered endpoint. This pack registers only endpoints the official Intercom REST API reference documents: the contacts, companies and conversations collection reads, and replying to a conversation.

All read capabilities cover the collection read only: single-record reads (GET /contacts/{id}, GET /companies/{id}, GET /conversations/{id}), search, scroll and per-contact sub-resource listings (notes, tags, segments, subscriptions) are not registered by this pack — separate navigation and sub-resource endpoints are not registered unless named.

Note on the companies collection read: it is verified against Intercom's retrievecompany reference itself, which documents the collection operation — GET /companies returns a paginated list of all companies, filterable by segment_id or tag_id, and fetches a single company by the name or company_id query parameters on the same path; the retrieval reference does document the general collection listing on this path.

The POST /companies/list variant named in older documentation does not appear in the current reference (its page returns not-found), POST /companies is the create-or-update operation (not registered), and the scroll API is deliberately not registered.

Consequential effects: POST /conversations/{conversation_id}/reply with message_type 'comment' is an admin reply delivered to the contact in the Messenger and by email — the unrestricted effect of the endpoint includes transmitting to the customer, so the capability declares send at the minimum R3 tier alongside create. Send is one of the designated actions requiring human approval: a reply cannot be recalled after delivery once the contact has it.

An internal-note-only variant (message_type 'note') is not registered: message_type is a request-body property of the same endpoint, and a pack registers an endpoint, not a body value, so nothing in the registration would enforce the note-only restriction.

Documented exclusions: this pack does not register contact create/update/delete, contact merge, archive or block, note creation, company create/update/delete, the Messages API (admin-initiated outbound messages, which are send at R3), conversation assignment or snooze, tags, and data-export endpoints.

Data-class rationale: contacts identify individuals (names, emails, phones, custom attributes) and conversations carry their messages, so both are pii; companies describe organizations and are registered internal. 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 (a workspace access token held in the customer's vault), with these findings, one per gated property.

Issuance authority and delegation: a workspace admin creates an app in the Intercom Developer Hub and the workspace's access token is issued from the app's Authentication section, so issuance authority sits with the workspace's own admin. Scope: Intercom scopes app permissions per resource in the Developer Hub; the app is built for the exact registered surface — read access to contacts, companies and conversations, plus conversation reply — and no other permission.

Audience: no audience mechanism is documented — the bearer value authorizes against api.intercom.io (or the workspace's regional host), and audience binding beyond that is not established. TTL: the retrieved authentication documentation states no expiry terms, corroborated by Intercom's own support channel — private-app access tokens do not expire unless manually revoked — so this pack treats the token as live until revoked.

Refresh ownership: there is no refresh — the token is the credential and no tokens are derived from it; the executor injects the stored value verbatim and performs no token lifecycle itself.

Revocation: the token is revoked by deleting or rotating it in the Developer Hub or by uninstalling the app, and a revoked value fails closed; because no derived tokens exist, deletion revokes exactly this value. Executor access and replay/exposure: the executor reads only the vault reference; the token is a bearer credential replayable with no TTL bound until revoked, so the vault reference is the only place the value may live.

Alternate access paths: the Intercom UI and other apps retain access outside this pack, and deleting or rotating this token closes only this path. The credential review is complete. Assign accountable owners before deployment.