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

# Freshservice

> Let an agent work your Freshservice tickets, knowledge, and more — reads as each person, plus governed admin actions.

# Freshservice

The Freshservice integration lets an agent look things up and act in your
Freshservice instance while it's talking to someone — find their tickets, read
the latest notes, file a new ticket, search the knowledge base, and (when you
enable it) reassign or move a ticket.

It connects with **one API key** you supply once, and scopes what each person
sees by matching their email to a Freshservice requester:

* **On behalf of each person** — reads (their tickets, comments, new tickets they
  file) are matched to the asking person by resolving their email to a
  Freshservice **requester**. If no requester matches, the agent fails closed
  rather than showing someone else's records.
* **On behalf of your organization** — a few privileged actions (reassigning a
  ticket, changing its state) run under the same organization API key, governed
  by allowlists.

There is **no OAuth app to register** and **no per-person sign-in** — Freshservice
authenticates third-party API access with a per-agent **API key**, not an OAuth
app. Setup takes a few minutes and is done once per instance.

## What it can do

The agent works across Freshservice **record types** through one set of tools,
so "what tickets do I have open?" returns incidents and service requests
together, each as a clickable link.

| Record type                           | Read                                   | Comment | Update                                         |
| ------------------------------------- | -------------------------------------- | ------- | ---------------------------------------------- |
| Tickets (incidents)                   | Yes                                    | Yes     | Yes (assign / change state — org-authorized)   |
| Service requests                      | Yes                                    | Yes     | Off by default                                 |
| Changes / Releases                    | Yes                                    | Yes     | Read-only — governed by Freshservice's process |
| Problems, Tasks, Change/Problem tasks | Yes                                    | Some    | Off by default                                 |
| Requesters                            | Yes                                    | —       | Off by default (touches personal data)         |
| Agents                                | Yes                                    | —       | —                                              |
| Knowledge (Solutions)                 | Yes                                    | —       | —                                              |
| Catalog items                         | Yes                                    | —       | —                                              |
| Assets / CMDB, Releases               | **Off** (sensitive — turn on per type) |         |                                                |

Every record the agent mentions comes back with a deep link straight to it in
Freshservice.

## What it does **not** do (today)

* **Approving or rejecting approvals** and **ordering a catalog item** are not in
  this release.
* It does not manage assets/CMDB unless you explicitly turn those sensitive types
  on.
* It never invents access: user-scoped reads are filtered to the asking person's
  Freshservice requester (matched by email). An empty result means "nothing
  matched to you," not "nothing exists" — and if the person can't be matched to a
  requester, the agent says so instead of guessing.

## Set up the connection (API key)

You connect Freshservice with one **API key** plus your **subdomain**. There's no
OAuth app and no callback URL.

<Steps>
  <Step title="Get a Freshservice API key">
    In Freshservice, pick (or create) an agent with the access the assistant
    should have, open **Profile settings**, and copy the **API key** from the
    right rail. The agent's Freshservice role decides what the key can read and do.
  </Step>

  <Step title="Add the integration in Cobalt">
    From your agent, open **Integrations**, choose **Freshservice**, and in the
    **Authorization** tab enter your **subdomain** — the `acme` in
    `acme.freshservice.com` — and paste the **API key**. The key is stored
    encrypted and never shown again.
  </Step>

  <Step title="Save and name the integration">
    Review the capabilities, confirm, name the integration, and save. That's it —
    no per-person sign-in.
  </Step>
</Steps>

Reads are matched to each person automatically: when the agent runs a
user-scoped read, it looks up the asking person's email as a Freshservice
**requester** and scopes the results to them. If the person isn't a requester in
Freshservice, the agent says it can't match them rather than showing another
person's records.

## Privileged actions (optional)

Reassigning tickets and changing ticket state run under the **same organization
API key**, governed by allowlists you set.

<Steps>
  <Step title="Turn on privileged ticket actions">
    On the integration's **Capabilities** tab, enable **Privileged ticket
    actions** under "On behalf of your organization."
  </Step>

  <Step title="Set allowlists">
    List the agent groups a ticket may be reassigned to and the ticket-state
    transitions that are allowed. Anything outside the allowlist is refused or
    routed to a human.
  </Step>
</Steps>

Make sure the API key's Freshservice agent has the permissions these actions
need (assigning tickets, changing state); the org key is what performs them.

## Control what the agent may touch (Record types)

The **Record types** settings let you turn **read / comment / update** on or off
**per record type**.

* **Sensitive types** (assets/CMDB, releases) are **off by default**; turning one
  on asks you to confirm.
* **Updating requesters** touches personal data — it's off by default and always
  asks for confirmation when used.
* **Changes and releases** are read-only on purpose: their state is governed by
  Freshservice's own change/release process, not by ad-hoc edits.

The agent never writes a record it hasn't just read, refuses to write a record
that changed since it looked, and reports the record's **actual new state** after
an update — so you see what happened, not what was attempted.

## Troubleshooting

<Warning>
  **Subdomain format.** Enter only the subdomain (`acme`), not the full URL. The
  field rejects anything that isn't a valid Freshservice subdomain.
</Warning>

* **The agent says it can't match someone to Freshservice.** That person's email
  isn't a Freshservice **requester**. Add them as a requester (or correct their
  email) — the agent fails closed rather than show another person's records.
* **"I couldn't reach Freshservice just now."** A transient API or network error —
  try again. Persistent failures usually mean the subdomain or API key is wrong;
  re-paste the key (rotating it in Freshservice invalidates the old one).
* **An update is refused as "read it first" or "it changed since you read it."**
  That's the safety gate working — the agent re-reads and retries on its own.
* **A privileged action is refused with a permission error.** The API key's
  Freshservice agent doesn't have rights for that action — use a key from an agent
  with the needed permissions.
* **The agent says it can't find a ticket you know exists.** User-scoped reads are
  filtered to the asking person's requester; the ticket may belong to someone else.

## FAQ

<AccordionGroup>
  <Accordion title="Does each person need their own Freshservice login?">
    No. You supply one Freshservice API key. Reads are scoped to each person by
    matching their email to a Freshservice requester — no per-person sign-in and
    no OAuth app.
  </Accordion>

  <Accordion title="Will the agent expose tickets a person shouldn't see?">
    User-scoped reads are filtered to the asking person's matched requester, and
    if they can't be matched the agent fails closed. Note the API key's agent role
    still bounds what's reachable at all, and privileged actions deliberately act
    org-wide.
  </Accordion>

  <Accordion title="Can the agent change a ticket's status or owner?">
    Yes, when you enable privileged ticket actions and set the allowed groups and
    state transitions. Those run under the organization API key and are audited.
  </Accordion>

  <Accordion title="Why can't it edit a Change or Release?">
    Those follow Freshservice's governed change/release process, so the agent
    reads and comments on them but never edits their state directly.
  </Accordion>

  <Accordion title="Is anything turned on automatically that I should know about?">
    Sensitive record types (assets/CMDB, releases) and requester edits are off by
    default. You opt in per type, per action.
  </Accordion>
</AccordionGroup>

## Related

* [Integrations overview](/integrations/overview) — how integrations work in
  general.
* [How Cobalt works](/concepts/how-cobalt-works) — where integrations fit.