Caddi connects to Freshservice with an API key taken from an agent's profile. This is not an OAuth connection — there is no sign-in step and no redirect URI.
Create a dedicated integration agent for this. A Freshservice API key belongs to a specific agent and carries exactly that agent's permissions — and it stops working if the agent is deactivated. Using a real employee's key means the integration breaks when they leave.
Before you start
You'll need:
An agent account in Freshservice (requester-only accounts have no API key)
An agent role with the access your loops need — full access to Tickets, plus view access to Problems, Inventory, and Contracts covers most cases
Owner or Admin access to your Caddi organization
Your Freshservice subdomain
Step 1: Create a dedicated integration agent
Optional but strongly recommended — skip only if you're testing.
In Freshservice, create a new agent account for the integration, for example
caddi-integration@yourcompany.com.Assign it a role with the permissions your loops need. Grant full access to Tickets and view access to Problems, Inventory, and Contracts as a starting point.
Add agent-management permissions only if a loop needs to assign tickets to other agents. Leave account and role administration off.
Caddi can only do what this agent's role permits. Anything the agent couldn't do in the Freshservice UI will return a 403 through the API too.
Step 2: Copy the API key
Sign in to
https://<your-domain>.freshservice.comas the integration agent.Click the profile picture in the top right and choose Profile settings.
Complete the CAPTCHA if you're prompted with one.
Copy the API key from the right-hand column.
Step 3: Configure Freshservice in Caddi
This step must be completed by a Caddi organization owner or admin.
In Caddi, open Integrations in the left sidebar, then click the Integration Setup tab at the top of the page. This tab is only visible to organization owners and admins.
Find Freshservice in the list and click Configure.
Enter the following values:
Helpdesk Domain — your domain as it appears in your Freshservice web address. Enter
acmeincif you sign in atacmeinc.freshservice.com.API Key — the key from the integration agent's profile settings. All Caddi actions run with this agent's permissions.
Click Save Configuration. Caddi validates the credentials immediately — if something is wrong you'll see an error right away, and nothing is stored until validation passes.
How the connection behaves
One shared identity. Every Caddi user acting on Freshservice does so as the agent whose key you entered. Freshservice attributes ticket activity to that agent.
Permissions come from the agent's role, not from scopes. To widen or narrow Caddi's reach, change the role in Admin → Roles.
The key dies with the agent. Deactivating or deleting the agent breaks the integration — the reason a dedicated service agent is worth setting up.
Changing the agent's password may regenerate the key. If the connection stops working after a password change, re-copy the key from Profile settings.
Rate limits are per-minute and depend on your plan — roughly 100 on Starter, 200 on Growth, 400 on Pro, and 500 on Enterprise. Individual endpoints have their own lower sub-limits.
If you use a vanity support URL, still supply the original
*.freshservice.comsubdomain here. That's the documented host for API access.
Troubleshooting
Authentication fails on save
Check the domain is the subdomain only — acmeinc, not acmeinc.freshservice.com or a full URL — and that the key came from an agent rather than a requester account.
Loops return 403 errors
Either the agent's role lacks that permission, or the feature isn't enabled on your Freshservice plan. Check the role in Admin → Roles first.
The connection stopped working after someone left
The key belonged to their agent account. Create a dedicated integration agent, copy its key, and update Caddi — then this won't recur.
It stopped working right after a password change
The API key was likely regenerated. Re-copy it from the agent's Profile settings.
Still stuck? Contact Caddi support with the exact error message you're seeing and the time it occurred.
Automation ideas
Law Firms
New hire → onboarding ticket chain
Caddi reads an approved new-starter form and creates the full set of Freshservice tickets — accounts, hardware, access requests — assigned to the right teams.
Recurring incident → problem record
Caddi spots repeat tickets on the same asset or service and creates the problem record with the linked incidents already attached.
Asset renewal → procurement ticket
Caddi watches contract and warranty dates in Freshservice and raises the renewal ticket with enough lead time to act on it.