Freshservice

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.

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.

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.

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.

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.

Pre-requisites

An active Freshservice tenant and its default Freshservice domain.

Permission to create a Freshservice integration user, or access to an active agent’s API key.

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.

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.

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

Create a dedicated Freshservice integration user

Use this option if Integration Users is available in your Freshservice tenant.

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

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.

Alternative: Copy an existing agent’s API key

If your tenant does not offer integration users:

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

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.

Identify the Freshservice domain

In Freshservice, inspect the tenant address and identify its Freshservice hostname—for example, acme.freshservice.com.
If your organization uses multiple requester portals or a branded URL, ask your Freshservice administrator for the default portal’s Freshservice URL.
Record only the hostname for AirMDR’s Domain field:
acme.freshservice.com

Do not enter https://acme.freshservice.com/support/home, a secondary portal URL, or api.freshservice.com as the tenant domain.

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.

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.

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.

Sample Request

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"

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/ticketsendpoint.

Sample Response

A successful ticket-list request checks connectivity and permission to list tickets.

Configure Freshservice in AirMDR Integrations Dashboard

Navigate to AirMDR, provide the credentials and click Login
Navigate to the AirMDR Integrations Dashboard in the left navigation pane and select ADMIN → Integrations.
Use the search option, enter the keyword “Freshservice”, select the Connections tab, and click + New Connection button.

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>`

Expand Advanced Configuration if required. (Optional)

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.
In Expiry, select the date on which AirMDR should treat the stored Freshservice credentials as expired, according to your organization’s credential rotation policy.

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

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.

Click Save.

Skills provided by this Integration

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

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

Ticket communication

Skill	Purpose	Access
Create Freshservice Ticket Reply	Add a reply to a ticket, with optional `from`, `cc`, `bcc`, and user context.	Write

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

Go to AirMDR → Freshservice Integration page.
Select the Skills tab and click on the required listed skills.

Additional Information

🧰 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)
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)

🔄 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
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:

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

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

👉 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
🛠️ For Freshservice API or tenant issues, use the Freshservice Support portal or contact support@freshservice.com. Include the tenant domain, timestamp, affected action, and sanitized error details; never include the API key.

🛑 Data Flow & Security

Data exchangedAirMDR 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.

Getting Started

AirMDR Detections

Integrations

API Reference

AirMDR Product Suite

Pre-requisites

Setup Steps

Alternative: Copy an existing agent’s API key

Freshservice Credential Reference Table

Validate Connectivity

Configure Freshservice in AirMDR Integrations Dashboard

Skills provided by this Integration

Additional Information

​Pre-requisites

​Setup Steps

​Alternative: Copy an existing agent’s API key

​Freshservice Credential Reference Table

​Validate Connectivity

​Configure Freshservice in AirMDR Integrations Dashboard

​Skills provided by this Integration

​Additional Information

Pre-requisites

Setup Steps

Alternative: Copy an existing agent’s API key

Freshservice Credential Reference Table

Validate Connectivity

Configure Freshservice in AirMDR Integrations Dashboard

Skills provided by this Integration

Additional Information