Skip to main content

​
After this article

You’ll be able to connect Zendesk to Lumos to sync and provision Zendesk users (admins and agents), groups, and roles, and to log ITSM tickets in Zendesk when access is requested.

​
Capabilities

Lumos can also log an ITSM ticket in Zendesk when access is requested in the AppStore. See Phase 3 for the configuration.

​
Required plan and roles

  • Zendesk role: you must be a Zendesk Support Admin to complete setup. The OAuth client is created in the Admin Center, and role/entitlement sync uses an admin-level Zendesk API.
  • Permission scoping: the integration supports both read-only and provisioning connections via an OAuth client you create in Zendesk:
    • Provisioning: read, tickets:read, tickets:write, users:read, users:write
    • Read-only: read, users:read, tickets:read
  • The ticket scopes support data transfer (reassigning a departing user’s tickets). The users:write scope is required for suspend, delete, downgrade, and account creation.

​
Read-only access vs provisioning

Is read-only possible? Yes. The OAuth client you create in Zendesk can be scoped to read, users:read, and tickets:read for a read-only connection. What read-only requires. A Zendesk Support Admin creating an OAuth client in Admin Center (Apps and integrations → APIs → OAuth clients) with the read, users:read, and tickets:read scopes. Follow the steps below. What full provisioning requires. The same OAuth client scoped instead to read, tickets:read, tickets:write, users:read, and users:write. The users:write scope specifically is what enables suspend, delete, downgrade, and account-creation actions. Watch out for. Role and entitlement sync uses an admin-level Zendesk API regardless of which scope set you choose, so a Support Admin is required either way. Deletion in Zendesk is permanent and irrecoverable. Reassign tickets with Transfer Data before deleting someone. Suspending a user doesn’t reclaim their license. Use Downgrade License or Delete for that. If you switch an existing OAuth client from read-only to provisioning scopes or the reverse, update the scopes on that same client in Zendesk. A connection failure right after a scope change points at a scope missing from the set for the mode you picked.

​
Instructions

Phase 1: Create the OAuth client in Zendesk
  1. Log into your Zendesk instance and open the Admin Center (top-right navigation).
  2. In the left menu, go to Apps and integrations → APIs → OAuth clients.
  3. Click Add OAuth client and fill in the required fields. The Identifier is your Client ID.
  4. Paste https://app.lumosidentity.com/integrations/ics_oauth2_callback into the Redirect URLs field.
  5. Select the scopes for your connection mode (see Required plan and roles above).
  6. Click Save and generate the Secret key. This is your Client Secret. Copy it immediately.
Phase 2: Connect in Lumos
  1. Find the Zendesk card in your Lumos integrations (reconnect an existing card or add a new one).
  2. App Instance Identifier: your Zendesk subdomain. For https://example.zendesk.com, enter example.
  3. Enter the Client ID (the OAuth client’s Identifier) and Client Secret.
  4. Click Connect.
Phase 3: Configure ITSM logging (optional) First, you will need to connect Zendesk (ITSM) by providing the subdomain and hitting enter: The Zendesk ITSM integration uses the following scopes. Once Zendesk is connected, you can set up ITSM logging so Lumos logs a ticket in Zendesk every time someone requests access to an app.
  1. In Lumos, go to your ITSM settings, choose Zendesk in the dropdown, and click Connect.
  2. Choose the sync you want to configure.
  3. Specify the Project, Request Type, and Resolve With values.
    • Project maps to your active Zendesk Groups (the groups endpoint).
    • Request Type lists the non-deleted ticket forms in your Zendesk instance (the ticket_forms endpoint). Ticket forms are not filtered by Zendesk Group.
    • Resolve With lists the active custom statuses you’ve created in Zendesk that map to a Solved ticket status (the custom_ticket_statuses endpoint). If you have no custom statuses, Lumos shows the Closed transition instead.
  4. Click Save.

​
API Endpoints Used

​
Troubleshooting

Connection or sync fails with authorization errors. Confirm the OAuth client has every scope for your connection mode, the redirect URL is exactly https://app.lumosidentity.com/integrations/ics_oauth2_callback, and the connecting user is a Zendesk Support Admin. End-users don’t appear in Lumos. Expected: the integration syncs admins and agents only. Create Account fails with a role validation error. There is a known issue where the UserRole value configured in the Lumos provisioning settings may not be applied to the created account, causing a role validation failure. If you hit this, contact Lumos Support. Deleted user data is gone. Deletion is permanent in Zendesk and deleted users are not recoverable. Use Transfer Data (Inactivity Workflows) or reassign tickets before deleting. License not freed after suspending. Expected: suspension does not reclaim a Zendesk license. Use Downgrade License or Delete to reclaim seats.