Integrating Help Scout
Auth: OAuth 2.0 · Partner program: not required · Setup time: about 20 minutes · Last verified: 2026-05-23
Help Scout is a shared-inbox / help-desk platform aimed at small teams. The adapter wraps the Mailbox API v2 and surfaces conversations, customers, mailboxes, and users into the canonical customer-support schema.
Auth model
Section titled “Auth model”- OAuth 2.0 Authorization Code grant. Authorize at
https://secure.helpscout.net/authentication/authorizeClientApplication. Exchange via POST tohttps://api.helpscout.net/v2/oauth2/token. - Access tokens last
172800seconds (2 days). Refresh tokens rotate on every refresh — store the new one each time. A 401 from the API is the canonical “token expired” signal. - A Client Credentials flow is also available for internal-use integrations against a single Help Scout account.
Prerequisites
Section titled “Prerequisites”- A Help Scout account with admin rights at secure.helpscout.net.
- A registered application under Your Profile → My Apps. Note the App ID (client id) and App Secret, and register the exact redirect URI.
Configure in admin
Section titled “Configure in admin”- Open
/platformsin the admin UI, filter to Customer Support, click Help Scout. - Fill Configure:
clientId— your Help Scout App ID.clientSecret— your Help Scout App Secret.redirectUri—${PUBLIC_BASE_URL}/auth/customer-support/helpscout/callback.
- Enable the adapter.
Required scopes
Section titled “Required scopes”Help Scout does not enforce OAuth scopes — the issued token inherits the role + permissions of the authorizing user. Have the connecting user be an account owner if you need full Mailbox API access; otherwise the adapter will silently 403 on writes they cannot make in the UI.
Webhooks
Section titled “Webhooks”Configure under Manage → Webhooks. Help Scout signs each delivery with HMAC-SHA1 (base64) in the X-HelpScout-Signature header — the adapter verifies the secret you supply against the raw body.
Subscribe to convo.*, convo.note.*, convo.reply.*, and customer.* events at minimum.
Quirks worth knowing
Section titled “Quirks worth knowing”- Refresh tokens rotate. Always persist the new
refresh_tokenreturned from a refresh call — the previous one is invalidated immediately. - Rate limit is account-wide. 400 requests per minute per Mailbox API client, shared across all installed integrations under the same app.
- No “list everything” endpoint for threads. Pull conversations first, then drill in — the adapter does this in two passes.
- Webhook signature is SHA-1, not SHA-256. A common bug when porting verification code from other Help Scout-style platforms.
References
Section titled “References”opensteward.dev ·Plans and free license ·Terms ·Privacy ·support@opensteward.dev
© 2026 Falco Consulting AB. Built from open-steward/opensteward@a3961d8. This site sets no cookies, runs no analytics and loads nothing from other sites, except platform logos from Brandfetch on the Platforms page.