Integrating Kustomer
Auth: OAuth 2.0 · Partner program: not required · Setup time: about 20 minutes · Last verified: 2026-05-23
Kustomer (Meta) is a customer-context-first support platform — conversations are organised around a customer timeline rather than tickets. The adapter wraps the Kustomer REST API and surfaces conversations, customers, messages, and users into the canonical customer-support schema.
Auth model
Section titled “Auth model”- OAuth 2.0 Authorization Code grant. Authorize at
https://api.apps.kustomerapp.com/oauth/authorize. Exchange via POST tohttps://api.apps.kustomerapp.com/oauth/token. - Access tokens last
86400seconds (1 day). Refresh tokens expire after two weeks of inactivity — re-prompt the user if your worker has been idle. - The adapter also accepts a static API key (created under Settings → Security → API Keys) for single-tenant deploys.
Prerequisites
Section titled “Prerequisites”- A Kustomer org at kustomer.com.
- A registered private OAuth app under the apps platform. Install the app before initiating the OAuth flow — Kustomer returns
400 Invalid Clientif you try to authorize an uninstalled app. - Note the Client ID and generated Client Secret.
Configure in admin
Section titled “Configure in admin”- Open
/platformsin the admin UI, filter to Customer Support, click Kustomer. - Fill Configure:
clientId— from your Kustomer OAuth app.clientSecret— from your Kustomer OAuth app.redirectUri—${PUBLIC_BASE_URL}/auth/customer-support/kustomer/callback.
- Enable the adapter.
Required scopes
Section titled “Required scopes”Request at minimum:
org.permission.customer— read / write customers.org.permission.conversation— read / write conversations and messages.offline_access— required to receive a refresh token.
Additional org.permission.* scopes exist for teams, settings, search, and workflow if you need them.
Webhooks
Section titled “Webhooks”Kustomer signs webhook deliveries with HMAC-SHA256 — supply a shared secret when you create the webhook subscription under Settings → Webhooks. The signature header is x-kustomer-signature (hex). Subscribe to customer.*, conversation.*, and message.* events.
Quirks worth knowing
Section titled “Quirks worth knowing”- Install before authorize. This is the single most common setup error — apps have to be installed to the org before the OAuth dance, not after.
- Refresh tokens decay on idle. Two weeks of no activity = full re-auth.
- Permission model is role-based. Scopes are coarse; effective permissions come from the API role attached to the app.
- Timeline-centric data model. Kustomer does not have “tickets” in the Zendesk sense — conversations live on the customer timeline. Map carefully.
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.