> ## Documentation Index > Fetch the complete documentation index at: https://docs.cobalt.peoplereign.io/llms.txt > Use this file to discover all available pages before exploring further. # Freshdesk > Let an agent work your Freshdesk tickets and knowledge base — scoped to each person, with Cobalt enforcing the boundary. # Freshdesk The Freshdesk integration lets an agent look things up and act in your Freshdesk account while it's talking to someone — find their tickets, read the replies and notes, post a reply, file a new ticket, and search your solution articles. It connects with **one API key** you supply once, and scopes what each person sees to their own Freshdesk contact. * **On behalf of each person** — ticket reads are filtered to the Freshdesk contact matching the asking person's verified identity. If Cobalt can't work out who they are, it says so rather than showing anyone else's tickets. * **On behalf of your organization** — a few privileged actions (reassigning a ticket, changing its state, editing a contact) run under the same organization API key, governed by the settings you choose. There is **no OAuth app to register** and **no callback URL to configure**. Freshdesk doesn't offer per-person sign-in for third-party apps, so there is nothing for your people to connect or approve. ## What you should understand before you set this up This one is worth reading twice, because it's different from most integrations. **The API key is organization-wide.** It can read every ticket in your Freshdesk account. Freshdesk has no way to give Cobalt a narrower, per-person credential. **So Cobalt — not Freshdesk — enforces the per-person boundary.** Before the agent reads any tickets, Cobalt matches the person asking to exactly one Freshdesk contact, and filters every ticket read to that contact. **When it can't match someone, it refuses.** It does not fall back to the organization key, and it does not quietly return an empty list. It tells the person it couldn't confirm who they are and points at a remedy. An empty result means "you have no matching tickets"; a refusal means "I don't know who you are" — and the agent will never confuse the two. ## Setting it up ### 1. Create or choose a Freshdesk agent Cobalt acts as a Freshdesk agent. Create one for it, or pick an existing one. * Make it an **occasional agent** if you can. Occasional agents don't consume a paid seat. * Give it a role with **Global ticket scope**. Without it, Cobalt can only see the tickets in that agent's own group — which looks exactly like the integration being broken. ### 2. Copy the API key In Freshdesk, open **Profile Settings → View API Key**. Freshdesk shows a captcha, then reveals the key. ### 3. Paste it into Cobalt Open the integration's **Authorization** tab and enter: * **Freshdesk subdomain** — the bare label only. For `acme.freshdesk.com`, enter `acme`, not the full address. * **Freshdesk API key** — the key you just copied. It's stored encrypted and is never shown again. Press **Save**, then **Verify**. Verify makes a real call to Freshdesk and shows you which agent Cobalt is acting as, so you can confirm you pasted the key you meant to. ### 4. Choose what it can reach On the **Policies** tab, the record-type table controls which kinds of Freshdesk record the agent may read, comment on, or update. Tickets and knowledge are on by default; **companies are off** until you turn them on. Contact summaries never include email or phone addresses. ## How people are identified Cobalt matches someone to a Freshdesk contact using the verified identity they already have — their SCIM directory record, their SSO sign-in, or the directory look-up behind their Slack or Teams account. It then finds the Freshdesk contact with **exactly** that email address. You can tune this on the Authorization tab: * **Accepted ways of confirming identity.** You can *remove* methods to make the boundary stricter. You can't add new ones — the list you're shown is the maximum. * **Email senders are never accepted.** Someone emailing your helpdesk hasn't proved who they are, so an inbound email address is never used to decide what tickets to show. This isn't configurable. * **Shared mailboxes are refused.** An address like `support@` resolves to one real Freshdesk contact and would return the whole team's ticket history to whoever asked. Cobalt refuses those by default; the prefix list is editable in both directions. * **When it can't identify someone**, you choose whether they can still search knowledge-base articles (they can by default — articles aren't personal), and whether filing a ticket is refused or allowed but left unlinked. ### Watching that it's working The **Identity resolution health** panel on the Authorization tab shows how often Cobalt could and couldn't identify the person, and why. This matters more than it sounds. An integration that fails to identify *everybody* looks identical to one that nobody uses — both are quiet. If more than a quarter of requests go unidentified in a day, the panel warns you and names the leading reason. ## What the agent can do **Tickets** — search and read the asking person's own tickets, read the full reply and note history, post a public reply, add a note, and file a new ticket. **Knowledge** — search and read your solution articles. **Contacts and agents** — look people up by name for find-then-act. Contact summaries deliberately omit email and phone. **Privileged actions** (off unless you enable them) — reassign a ticket, change its state, or edit a contact record. These run under the organization key. Filing a ticket always files it **as the person asking**. There is no way to ask the agent to file one as somebody else, and if someone tries, it will say so. ## Troubleshooting **"I couldn't confirm which Freshdesk contact you are."** Cobalt matched the person to a verified identity but found no Freshdesk contact with exactly that email address. Check the health panel for the specific reason. The usual causes are: the person isn't a contact in Freshdesk yet; their Freshdesk contact uses a different address than their directory record; or their contact was blocked or deleted in Freshdesk (a blocked contact reads as "not found", and Cobalt fails closed rather than guessing). **The agent can't see tickets it should be able to see.** Check the Freshdesk agent's role has **Global ticket scope**. Without it, the key only reaches one group's tickets. **"Freshdesk rejected the organization API key."** The key was reset, revoked, or the agent was deactivated. Re-copy it from Profile Settings and Verify again. Note that **resetting a Freshdesk API key revokes it for every application using it**, not just Cobalt. **"Freshdesk is busy right now."** Freshdesk's rate limits are **account-wide** and shared with every other integration you run — and on the Growth plan, listing tickets is limited to 20 calls a minute. Cobalt reports the limit and waits for you rather than retrying, because a retry storm would degrade your own Freshdesk agents. ## Rotating the key Paste the new key on the Authorization tab and press Verify. Nothing else needs to change. Remember that resetting the key in Freshdesk affects every application that uses it.