> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lumos.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Zendesk

## 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

| Functionality | Type | Sync | Provision | Description |
| - | - | - | - | - |
| Users | Account | Yes | Yes | Admin and agent accounts (end-users are not synced). Last login is tracked |
| Groups | Permission | Yes | Yes | Zendesk groups |
| Roles | Permission | Yes | No | Zendesk role definitions, including custom roles |

| Deprovisioning Action | Type | Description |
| - | - | - |
| Deactivate | User | Suspends the user. They can't log in, and new requests from their identities go to the suspended tickets queue. Does not reclaim a license |
| Delete | User | Deletes the user (soft delete, then permanent delete). **Permanent and irrecoverable**, transfer important data first. Reclaims a license |
| Downgrade License | User | Sets the user's role to end-user and reclaims a license. Reassign their tickets first to prevent data loss |
| Transfer Data | User | Reassigns all of the from-user's requested tickets to the to-user. Available only in Inactivity Workflows |

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.

| **Scope** | **Required** | **Description** |
| :- | :- | :- |
| read | Yes | Read all data |
| write | Yes | Write all data |

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

<Note>
  The API endpoints this integration uses are available to logged-in Lumos customers. [Log in](/login) to view them.
</Note>

## 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.