Skip to main content
This is the Freshservice Provisioning integration: it creates, updates, activates, deactivates, and deletes Freshservice agents and manages their role assignments from Lumos. To sync agents and their roles and log Lumos access-request tickets to Freshservice without managing access, use Freshservice (ITSM) instead.

​
After this article

You will be able to connect Freshservice to Lumos to sync agents and roles and to provision and deprovision agent access.

​
Capabilities

The Agent license entitlement syncs read-only, so Lumos can track who holds an agent seat but doesn’t assign it directly. Activity tracking is supported. Lumos tracks agent last activity. Provisioning behavior:
  • Create: Lumos creates the agent with first name, email, and optional last name. Roles can’t be included at create time, so assign them afterward.
  • Assign a role: Lumos reads the agent’s current roles, appends the new role (scoped to the entire helpdesk), and writes the full role list back in one update.
  • Remove a role: Lumos reads the agent’s current roles, drops the matching role, and writes the remaining list back. Other roles are untouched.
  • Deactivate and reactivate: deactivating keeps the agent record and blocks the seat, and reactivating restores it.
  • Delete: permanently removes the agent using Freshservice’s forget endpoint. This is not reversible.

​
Required plan and roles

  • Freshservice role: the connecting user must be an Account Admin with access to the admin console. To confirm: Settings → User Management → Roles, then under Admin roles check you are listed as an agent for the Account Admin role.
  • Credential model: the connector authenticates with OAuth 2.0 through a Freshworks OAuth app you create in the Freshworks Developer Portal (Client ID and Client Secret). This card does not take an API key.
  • Scopes requested by the OAuth app:
    • freshservice.agents.manage (required): create, update, activate, deactivate, and delete agents, and read and write their role assignments
    • freshservice.agents.roles.view (required): list agent roles
    • freshservice.requesters.view (required): view requester records during account sync

​
Instructions

Phase 1: Create OAuth credentials in Freshworks
  1. Go to https://<your-freshworks-subdomain>.myfreshworks.com/developer.
  2. Click the cog wheel icon in the top right corner, then click Create OAuth Credentials.
  3. Add a name and description so you can identify the application later.
  4. Set the Redirect URL to https://app.lumosidentity.com/integrations/ics_oauth2_callback.
  5. For scopes, select FreshService and add freshservice.agents.manage, freshservice.agents.roles.view, and freshservice.requesters.view.
  6. Click Create Credentials, then copy the Client ID and Client Secret shown on the next page. You can go back and edit the application later if you need to fix a step.
Phase 2: Connect in Lumos
  1. Find the Freshservice Provisioning card in your Lumos integrations (reconnect an existing card or add a new one).
  2. Enter your FreshService Subdomain: the part before freshservice.com in your service desk URL (for https://companyname.freshservice.com, enter companyname).
  3. Enter your Freshworks Subdomain: the part before myfreshworks.com in your Freshworks account URL.
  4. Enter the Client ID and Client Secret from Phase 1.
  5. Click Connect and approve the authorization in the Freshworks pop-up.

​
API Endpoints Used

​
Troubleshooting

Can’t connect the integration. Enter both subdomains without https:// or the domain suffix, confirm the OAuth app’s Redirect URL is exactly https://app.lumosidentity.com/integrations/ics_oauth2_callback, and check that all three Freshservice scopes are selected on the app. Provisioning actions fail. The freshservice.agents.manage scope is required to create, update, and deactivate agents and to change their roles, and freshservice.agents.roles.view is required to read roles. Check the scopes on the OAuth app in the Freshworks Developer Portal, then reconnect the card so the new grant takes effect.