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

# Freshservice

> The integration lets authorized AirMDR workflows access Freshservice records through the Freshservice REST API. The records AirMDR can read or change depend on the Freshservice account’s permissions and the AirMDR skills enabled for the connection.

<AccordionGroup>
  <Accordion title="Purpose">
    To connect Freshservice to AirMDR using your Freshservice domain and an API key. This guide shows how to obtain both values in the Freshservice UI, enter them in AirMDR, and configure the optional **Remote Agent** and **Expiry** fields shown in the connection form.
  </Accordion>

  <Accordion title="Supported Versions">
    | Component | Compatibility |
    | :- | :- |
    | Freshservice | Cloud tenant with access to the Freshservice REST API v2 |
    | Authentication in the AirMDR form | Freshservice **API Key** and **Domain** |
    | Freshservice account type | An integration user, where available, or an active agent with appropriate permissions |
    | AirMDR version and supported skills | Confirm against the skills available in your AirMDR organization; the supplied connection screen does not specify a version or skill list |

    Freshservice supports API keys for dedicated **integration users**. These accounts are intended for integrations, cannot sign in to the portal, and can be assigned workspace or account-wide roles. Freshservice currently excludes MSP multi-account architectures from this feature.<br />
  </Accordion>

  <Accordion title="Authentication">
    AirMDR’s displayed connection form requires an **API Key**, not an OAuth client ID or access token. For a direct API test, Freshservice accepts HTTP Basic authentication with the API key as the username and `X` as the placeholder password. A normal Freshservice username and password should not be used for API v2 authentication.

    The key acts with the permissions of its Freshservice identity. Assign only the roles and workspace access needed for the AirMDR actions you intend to use. A successful authentication does not grant access to records outside that identity’s permissions.

    <Accordion title="Credential reference">
      | AirMDR field | What to enter | Where to get it |
      | :- | :- | :- |
      | **Domain** | The default portal’s Freshservice hostname, for example `acme.freshservice.com`. Omit `https://`, paths, and trailing slashes. | Check the hostname of your Freshservice tenant. If your account has multiple portals, confirm the **default portal’s Freshservice URL** with your administrator. |
      | **API Key** | The key copied from the selected Freshservice integration user or agent profile. | **Integration user:** `Global Settings → User Management → Integration Users → [user] → API key`. **Agent:** profile icon → **Profile settings**→ **Your API Key**. |
      | **Remote Agent** | An AirMDR Remote Agent selected only when your deployment requires requests to originate through it. | AirMDR **Advanced Configuration** dropdown. |
      | **Expiry** | A date chosen for managing this credential in AirMDR. | AirMDR **Advanced Configuration** date picker; this date is not obtained from the Freshservice API-key screen. |

      <Note>
        Freshservice says REST API requests must use the **default portal’s Freshservice URL**. Do not substitute a secondary portal URL or the default portal’s custom URL.
      </Note>
    </Accordion>
  </Accordion>
</AccordionGroup>

## Pre-requisites

> <Check>
>   An active Freshservice tenant and its default Freshservice domain.
> </Check>
>
> <Check>
>   Permission to create a Freshservice integration user, or access to an active agent’s API key.
> </Check>

## Setup Steps

AirMDR can connect using the API key of a **dedicated integration user** or an **existing agent**. Both options use the same **Domain** and **API Key** fields in AirMDR. Choose the identity based on how your organization manages access.<br />

<Accordion title="Refer Freshservice **Dedicated integration user** or **Existing agent’s API key** for better understanding">
  | Option | Best suited for | Consideration |
  | :- | :- | :- |
  | **Dedicated integration user** | A long-term AirMDR connection | Has its own API key and assigned roles, so the connection does not depend on an employee’s account. Use this option when **Integration Users** is available in your Freshservice tenant. |
  | **Existing agent’s API key** | Tenants where integration users are unavailable | Uses that agent’s permissions. Changes to the agent’s access or account status can affect the connection. |

  <Note>
    For either option, grant access only to the Freshservice workspaces and actions required by the AirMDR skills you plan to use.
  </Note>
</Accordion>

<Steps>
  <Step title="Create a dedicated Freshservice integration user">
    Use this option if **Integration Users** is available in your Freshservice tenant.

    1. Sign in to Freshservice with an administrator account authorized to manage integration users.
    2. Go to **Global Settings → User Management → Integration Users**.
    3. Select **Create integration user**.
    4. Enter a descriptive **Display name**, such as `AirMDR Integration`, and a **Description** explaining its purpose.
    5. Select **Create**.
    6. Open the new user and, on the **Permissions** tab, select **Add to workspace**.
    7. Choose each workspace AirMDR must access. Under **Roles**, select a role with the required permissions, then select **Save**.
    8. Add an account-wide admin role only if an approved AirMDR action specifically needs account-wide administrative access.
    9. On the user’s **API key** card, select **Show**, then **Copy**. Store the key securely until you enter it in AirMDR.

    <Note>
      Freshservice requires administrator permissions to create and manage integration users; the exact permissions include access to integration users and, for rotation, the ability to reset their API keys.
    </Note>

    ### Alternative: Copy an existing agent’s API key

    If your tenant does not offer integration users:

    1. Sign in as the Freshservice agent whose permissions will be used for AirMDR.
    2. Select your **profile icon** in the upper-right corner.
    3. Select **Profile settings**.
    4. Find **Your API Key** on the right side of the page, below **Delegate Approvals**. Complete the verification prompt if one appears.
    5. Copy the key. Confirm that this agent is active and has the required roles and workspace access.

    <Note>
      An agent’s API key is associated with that agent’s access. If the account is deactivated or its permissions change, integration actions can be affected.
    </Note>
  </Step>

  <Step title="Identify the Freshservice domain">
    1. In Freshservice, inspect the tenant address and identify its Freshservice hostname—for example, `acme.freshservice.com`.
    2. If your organization uses multiple requester portals or a branded URL, ask your Freshservice administrator for the **default portal’s Freshservice URL**.
    3. Record only the hostname for AirMDR’s **Domain** field:
       ```text theme={null}
       acme.freshservice.com
       ```

    <Info>
      Do not enter `https://acme.freshservice.com/support/home`, a secondary portal URL, or `api.freshservice.com` as the tenant domain.
    </Info>
  </Step>
</Steps>

## Freshservice Credential Reference Table

| AirMDR field | What to enter | Where to get it |
| :- | :- | :- |
| **Domain** | The default portal’s Freshservice hostname, such as `acme.freshservice.com`. Do not include `https://` or a URL path. | Copy the hostname from your Freshservice tenant URL. If your organization has multiple portals, confirm the default portal’s Freshservice URL with your administrator. |
| **API Key** | The API key for the identity authorized to perform the required AirMDR actions. | **Integration user:** **Global Settings → User Management → Integration Users → \[user] → API key → Show → Copy**. **Existing agent:** profile icon → **Profile settings → Your API Key**. |

<Note>
  Freshservice API requests must use the default portal’s Freshservice URL, and the API key’s access is governed by its integration user’s or agent’s assigned permissions.
</Note>

## Validate Connectivity

Use the following request to confirm a read-only API request:

Run this optional check from an approved terminal that can reach the tenant. It lists tickets visible to the key’s Freshservice identity; a successful response may contain an empty list if no tickets are visible.

<AccordionGroup>
  <Accordion title="Sample Request">
    ```json theme={null}
    read -r -s -p "Freshservice API key: " FS_API_KEY
    printf '\n'

    curl --fail-with-body --silent --show-error \
      --user "${FS_API_KEY}:X" \
      --header "Accept: application/json" \
      "https://acme.freshservice.com/api/v2/tickets"
    ```

    <Note>
      Replace `acme.freshservice.com` with your default Freshservice hostname. Avoid adding `--verbose` or sharing terminal output containing credentials. Freshservice’s API documentation shows the API-key-as-username pattern and the `/api/v2/tickets`endpoint.
    </Note>
  </Accordion>

  <Accordion title="Sample Response">
    A successful ticket-list request checks connectivity and permission to list tickets.
  </Accordion>
</AccordionGroup>

## Configure Freshservice in AirMDR Integrations Dashboard

1. Navigate to [AirMDR](https://app.airmdr.com/auth/login), provide the credentials and click **Login**
2. Navigate to the AirMDR Integrations Dashboard in the left navigation pane and select **ADMIN → Integrations**.
3. Use the search option, enter the keyword "**Freshservice**", select the **Connections** tab, and click **+ New Connection** button.
4. Use the following values in the AirMDR integration configuration screen:

   | AirMDR field | Required | Description | Example |
   | :- | :- | :- | :- |
   | **Instance** | Yes | A unique name that identifies this Freshservice connection. | `Freshservice-Production` |
   | **Organization** | Yes | The AirMDR organization associated with the connection. Select it from the dropdown. | `ASO – AirMDR System Organization` |
   | **Description** | Yes | A short description of the connection’s purpose. | `Production IT service desk connection` |
   | **Domain** | Yes | The default portal’s Freshservice hostname, without `https://` or a URL path. | `acme.freshservice.com` |
   | **API Key** | Yes | The key copied from the dedicated Freshservice integration user or an authorized agent’s profile. | `<Freshservice API key>` |

   <Accordion title="Expand Advanced Configuration if required. (Optional)">
     1. In **Remote Agent**, select an AirMDR Remote Agent only when requests to your Freshservice tenant must pass through an approved network route, proxy, or controlled environment. For a publicly accessible Freshservice tenant, leave this field unselected unless your AirMDR administrator instructs otherwise.
     2. In **Expiry**, select the date on which AirMDR should treat the stored Freshservice credentials as expired, according to your organization’s credential rotation policy.

     <Note>
       The **Expiry** date applies to the connection in AirMDR. It does not automatically reset or revoke the API key in Freshservice.
     </Note>

     <Note>
       When rotating the key, reset it in Freshservice, update the AirMDR connection with the new key, and validate the connection. Resetting a Freshservice integration user’s key immediately breaks applications that still use the old key. 
     </Note>
   </Accordion>
5. Click **Save**.

## Skills provided by this Integration

<AccordionGroup>
  <Accordion title="Ticket retrieval">
    | Skill | Purpose | Access |
    | :- | :- | :- |
    | **Search Freshservice Tickets** | Search for tickets using optional filters. | Read |
    | **List Freshservice Ticket Conversations** | Retrieve a ticket’s conversations with pagination. | Read |
  </Accordion>

  <Accordion title="Ticket creation and updates">
    | Skill | Purpose | Access |
    | :- | :- | :- |
    | **Create Freshservice Ticket** | Create a new ticket. | Write |
    | **Update Freshservice Ticket** | Update an existing ticket using only the fields provided. | Write |
    | **Create or Update Freshservice Ticket** | Create a ticket or update an existing one, depending on the supplied inputs. | Write |
  </Accordion>

  <Accordion title="Ticket communication">
    | Skill | Purpose | Access |
    | :- | :- | :- |
    | **Create Freshservice Ticket Reply** | Add a reply to a ticket, with optional `from`, `cc`, `bcc`, and user context. | Write |
  </Accordion>
</AccordionGroup>

<Tip>
  To view the details of Input Parameters and Output for the respective skills

  * Go to [AirMDR → Freshservice](https://app.airmdr.com/integrationsv2/ff6f8922-c62b-4cb7-a7e2-b9e4a1628b03/skills?search=fresh) Integration page.
  * Select the **Skills** tab and click on the required listed skills.
</Tip>

## Additional Information

<AccordionGroup>
  <Accordion title="🧰 Error Handling">
    | Symptom | Likely cause | Recovery |
    | :- | :- | :- |
    | **401 Unauthorized** | Incorrect or reset API key; wrong tenant domain; inactive identity. | Recopy the key, confirm the default Freshservice domain, and check that the integration user or agent is active. |
    | **403 Forbidden** | The identity authenticates but lacks access to the requested action or workspace. | Review its assigned roles, workspace scope, and the permissions required for that AirMDR skill. Also inspect the response for any rate-limit information before assuming it is purely a permission issue. |
    | **404 Not Found** | Wrong domain, resource path, or record ID; record outside accessible scope. | Confirm the default portal hostname and the endpoint used by the action. |
    | **Rate-limit response** | Too many API requests for the tenant’s applicable limit. | Respect any `Retry-After` response header, reduce polling frequency, and retry with backoff. Freshservice publishes plan-specific API call limits, so check the tenant’s current plan. ([freshworks.com](http://freshworks.com)) |
    | **Connection or TLS failure** | DNS, proxy, firewall, certificate, or Remote Agent connectivity problem. | Test name resolution and outbound HTTPS from the actual execution location. Check proxy policy and certificate validation. |
    | **Connection stops after key rotation** | AirMDR still has the previous key. | Copy the new key into the existing AirMDR connection and test an authorized read-only action. Freshservice warns that resetting an integration user’s key breaks apps using the old key. ([support.freshservice.com](http://support.freshservice.com)) |
  </Accordion>

  <Accordion title="🔄 Monitoring & Logs">
    * **In AirMDR:** Check the connection status and the execution history of the Freshservice skill or workflow that failed. Record the time, action, and HTTP status; keep the API key out of logs.
    * **In Freshservice:** Inspect the affected record’s **Activity** where applicable. For integration users, Freshservice also documents **Global Settings → Audit Log** and the integration user’s **Tickets** tab for relevant activity. An audit log is not a guaranteed trace of every API request. [support.freshservice.com](http://support.freshservice.com)
    * **Recommended logging:** Keep routine successful requests at `INFO`, transient failures at `WARN`, and failed authentication or authorization at `ERROR`. Log a request identifier when available, while redacting credentials and sensitive record content.

    Illustrative application logs, **not exact AirMDR output**:

    ```text theme={null}
    INFO  freshservice request completed action=list_tickets status=200
    WARN  freshservice request deferred action=list_tickets status=429 retry_after=30s
    ERROR freshservice request failed action=list_tickets status=403 reason=access_denied
    ```
  </Accordion>

  <Accordion title="🛑 Security & Access Best Practices">
    **✅ Do**

    * Use a dedicated Freshservice **integration user** for AirMDR when the feature is available.
    * Assign only the ticket permissions and workspace roles required by the AirMDR skills you enable.
    * Enter the API key only in AirMDR’s designated secret field or an approved secrets manager.
    * Use the default portal’s Freshservice domain and connect over HTTPS.
    * Keep production and non-production connections and credentials separate.
    * Review ticket activity and available integration-user audit logs for unexpected actions.
    * Rotate the API key according to your organization’s policy, then update and validate the AirMDR connection.
    * Reset the key promptly if exposure is suspected; investigate actions performed by that identity.

    **❌ Don’t**

    * Share the API key through email, chat, tickets, screenshots, or documentation.
    * Store the key in scripts, configuration files, or source-control repositories.
    * Use an employee’s personal API key when a dedicated integration user is available.
    * Grant account-wide administrator access solely to make the connection work; check the permission needed for the failing skill.
    * Use a secondary portal or branded custom URL as the Freshservice API domain.
    * Assume a successful connection test confirms permission for ticket creation, updates, and replies.
    * Assume AirMDR’s **Expiry** field resets or revokes the Freshservice API key.
    * Reset a key without updating dependent connections: Freshservice warns that applications using the previous key will stop working.
  </Accordion>

  <Accordion title="👉 Support & Maintenance">
    * 📧 Contact **AirMDR Support** through your designated support channel for connection or skill execution issues.
    * 🔄 Rotate the Freshservice API key according to your organization’s security policy. If your policy specifies a 90-day cycle, schedule the AirMDR **Expiry** date to support that review.
    * 🔁 Update the **API Key** in AirMDR immediately after resetting it in Freshservice, then validate the connection with a read-only action. Resetting an integration user’s key stops applications that use the previous key. [support.freshservice.com](https://support.freshservice.com/support/solutions/articles/50000014413-manage-integration-users-in-freshservice?utm_source=chatgpt.com)
    * 🛠️ For Freshservice API or tenant issues, use the [Freshservice Support portal](https://support.freshservice.com/support/home?utm_source=chatgpt.com) or contact `support@freshservice.com`. Include the tenant domain, timestamp, affected action, and sanitized error details; never include the API key.
  </Accordion>

  <Accordion title="🛑 Data Flow & Security">
    **Data exchanged**

    AirMDR sends authenticated HTTPS requests to `https://<domain>/api/v2/...`. Freshservice returns the records or action results permitted for the API-key identity. The specific data exchanged—such as ticket fields, requester details, or updates—depends on the AirMDR skill invoked and its Freshservice endpoint. Review the enabled skills and their permissions before granting access.

    | Item | Guidance |
    | :- | :- |
    | **In transit** | Use HTTPS and validate the tenant’s TLS certificate. HTTP Basic authentication carries the API key within the authenticated request, so do not send it over plain HTTP. |
    | **At rest** | Store the API key only in AirMDR’s designated secret field and approved credential stores. Confirm each product’s storage and encryption controls against your organization’s security documentation; the connection screen alone does not establish an encryption algorithm. |
    | **Network port** | Outbound TCP **443** to the default Freshservice hostname from the AirMDR execution location or selected Remote Agent. |
    | **API endpoint pattern** | `https://<domain>/api/v2/<resource>`; for the read-only example, `GET /api/v2/tickets`. |
    | **Access boundary** | Freshservice evaluates the active integration user’s or agent’s roles and permissions for API actions. |
  </Accordion>
</AccordionGroup>