Skip to Content
IntegrationsZendeskConnecting Zendesk

Connecting Zendesk

After the Flexivity AI marketplace app is installed, you need to run the OAuth connect flow to link your Zendesk account to a Flexivity AI instance. This step grants Flexivity the permissions it needs to read and write Zendesk data, and provisions the webhook that delivers ticket events to Flexivity in near-real-time.

The connect flow is always initiated from the Flexivity admin console at app.flexivity.ai  — there is no “Connect” button on the Zendesk-side app settings page. The marketplace install is a prerequisite (see Marketplace Installation); the OAuth grant runs after you click Connect Zendesk in the admin console.

Before You Begin

Confirm:

  • You completed the Marketplace Installation step.
  • You have a Zendesk admin role on the account.
  • You have a Flexivity AI account at app.flexivity.ai . If you do not, sign up before continuing — the connect flow is run from inside the admin console, so an account is required to start it.

Step 1: Initiate the Connect Flow

  1. Sign in to app.flexivity.ai .
  2. Navigate to Instances. If you do not yet have a Zendesk instance, click Create Instance and select Zendesk as the product type.
  3. Open the Zendesk instance and click Connect Zendesk. You will be prompted to enter the Zendesk subdomain you want to connect — the part before .zendesk.com in your Zendesk URL (for example, acme if your Zendesk is https://acme.zendesk.com). Have this ready before you click; the redirect uses it to take you to the right Zendesk account.
  4. You are redirected to that Zendesk subdomain to grant OAuth. You must be signed in to Zendesk as an admin in the same browser session for the OAuth consent screen to render — if you are not, Zendesk prompts you to sign in first. (If the marketplace app has not been installed yet, Zendesk will surface a message asking you to install it first — complete Marketplace Installation and then retry.)

Step 2: Grant OAuth Scopes

You will see Zendesk’s standard OAuth consent screen showing the scopes Flexivity is requesting.

Flexivity requires two OAuth scopes:

  • read — read tickets, comments, custom fields, audit events, users, groups, help center articles.
  • write — write ticket updates (the topic field for AI Classification), create webhook subscriptions, install the app configuration, create Help Center draft articles, rotate the per-install JWT secret.

Note: Zendesk’s OAuth scopes are coarse — read and write are the only options at the marketplace tier. Flexivity requests both because several features (Classification writes to the topic field, KB Authoring writes drafts to Help Center, OAuth-managed JWT secret rotation writes to the app installation) require write access. There is no fine-grained “read-only” or “tickets-only” alternative scope on Zendesk’s side today.

Review the scopes and click Allow to grant them.

If you click Cancel or Deny, you are returned to the Flexivity admin console with the connection in Pending state. You can retry from either the Zendesk app settings or the Flexivity admin console at any time.

Step 3: Connection Confirmation

After you grant OAuth, Zendesk redirects back to Flexivity. The Flexivity admin console:

  1. Exchanges the OAuth authorization code for an access token and refresh token (both stored encrypted server-side).
  2. Provisions the webhook subscription on your Zendesk account that delivers ticket events to https://api.flexivity.ai/v1/zendesk/webhook.
  3. Generates a per-install JWT secret and writes it back to the marketplace app’s installation settings via the Zendesk Apps API (used to authenticate the ZAF widget’s requests to Flexivity).
  4. Seeds the picklist cache from your Zendesk custom fields (for AI Classification).
  5. Marks the instance as Active in the admin console.

You can verify the webhook landed by checking Zendesk: Admin Center → Apps and integrations → Webhooks. Look for a webhook named Flexivity AI Events with endpoint https://api.flexivity.ai/v1/zendesk/webhook.

Tip: The webhook signing secret Flexivity uses to verify webhook payloads is created behind the scenes during connect and stored encrypted in Flexivity’s Secrets Manager. You do not need to handle it manually.

Step 4: Verify and Configure

Now that the instance is active:

  1. Open a test ticket in Zendesk Agent Workspace. The Flexivity AI widget should appear in the ticket sidebar. Initially the Summary section may show “Processing…” for a few seconds while the first event flows end-to-end.
  2. Return to the Flexivity admin console and proceed to Feature Configuration to enable individual features (Summaries, Recommendations, Classification, KB Analysis) and tune their settings.

OAuth Token Refresh

Zendesk OAuth access tokens are short-lived (approximately 30 minutes in practice, despite the expires_in claim suggesting longer). Flexivity automatically refreshes tokens using the refresh token as needed — there is nothing you need to do.

If a refresh ever fails (for example, the refresh token was invalidated by an admin revoking the OAuth grant), the instance status changes to Reauthorization required in the Flexivity admin console, and re-running the connect flow re-establishes the OAuth grant. See Troubleshooting — OAuth refresh failures.

Disconnecting

To disconnect the Zendesk integration:

  1. In the Flexivity admin console, open the Zendesk instance and click Disconnect. This:

    • Revokes the OAuth grant on Zendesk’s side.
    • Removes the webhook subscription from your Zendesk account.
    • Marks the instance as Disconnected in Flexivity.

  2. (Optional) Uninstall the marketplace app from Zendesk if you also want to remove the agent-facing widget — see Marketplace Installation — Uninstalling.

Next Steps

Connection alone is not enough for a working system. Once OAuth is granted, two more things need to happen before Flexivity’s AI features can produce useful output:

  • Historical ticket sync — kicks off automatically the moment you grant OAuth. It backfills your existing solved tickets into the embedding index so Recommendations, Classification, and KB Analysis have data to work with from day one. Monitor progress and adjust the sync window in Feature Configuration → Historical Sync Period.
  • Classification topic field — for AI Classification to set or suggest a topic value, point Flexivity at the Zendesk custom dropdown field that represents your topic taxonomy. Configure in Feature Configuration → Classification Topic Source.

Then continue with:

Last updated on
Marketplace InstallationFeature Configuration