Freshservice

This role grants the integration account read-only access to the reference and administrative objects it needs (agents, roles, groups, departments, locations, surveys, and SLA/business-hours metadata). In Freshservice this is created as an "Admin" role type because those reference objects live under the admin permission set — but it is view-only and grants no ability to change settings or write data. Creating a dedicated role (rather than reusing an existing one) keeps the integration's permissions scoped tightly and makes them easy to audit and revoke.

1. Open the Admin panel. Click the Admin gear icon in the left sidebar of Freshservice.
2. Navigate to Roles. Under User Management, click Roles.
3. Click New Role. Give the role a clear name — for example, CIOAnalytics Reference Read-Only — and a description like Read-only access to reference data for the Info-Tech Customer Data Store integration.
4. Grant the following permissions:
   • View Agents and Agent Groups
   • View Roles
   • Manage Locations *
   • View Requesters
   • View Department
   • Manage Business Hours, SLA Policies, and OLA Policies *
   • View Surveys
5. Do not enable create, edit, delete, or write permissions beyond what is listed above. The integration is read-only and never writes back to Freshservice.
6. Save the role.

* This is a Freshservice UI limitation, not a write-back requirement. Freshservice does not offer a separate view-only toggle for Locations and for Business Hours / SLA / OLA Policies — it bundles read access under a single "Manage" permission, so enabling "Manage" is the only way to grant the read access the integration needs. The integration never creates, edits, or deletes these objects; the API key is used read-only.

This role grants the integration account read-only access to tickets and related operational data.

1. Navigate to Roles. Under User Management, click Roles (you should still be in the Admin panel from step 1).
2. Click New Role. Give the role a clear name — for example, CIOAnalytics Agent Read-Only — and a description like Agent-level read-only access for the Info-Tech Customer Data Store integration.
3. Grant the following permissions:
   • View Tickets
   • View or Edit Time Entries *
   • View Survey Responses
4. For Tickets, set the scope to View All Tickets. This ensures the integration sees every ticket across the tenant, not just tickets in a specific group or department.
5. Do not enable create, edit, delete, or write permissions beyond what is listed above.
6. Save the role.

* The integration only requires read access. Freshservice combines view and edit permissions for Time Entries into a single option, so enabling it is the only way to grant the read access we need. The integration will not edit Time Entries.

We will create a new agent account whose sole purpose is to host the API key. Using a dedicated agent (rather than tying the key to a person's account) means the key survives staff turnover and can be deactivated without affecting any human user. Both the Admin Role and Agent Role must be assigned to this agent.

1. Navigate to Agents. Under User Management, click Agents.
2. Click New Agent.
3. Fill in the agent details. Use a service-account email like cioanalytics@yourcompany.com. Suggested display name: CIOAnalytics. The mailbox does not need to be monitored — Freshservice only uses it for the initial activation email.
4. Assign both roles. Under Roles, select both CIOAnalytics Reference Read-Only (from step 1) and CIOAnalytics Agent Read-Only (from step 2). Do not assign any other roles.
5. Choose the agent license type. Use the license type approved by the customer's Freshservice administrator.
6. Save the agent. Freshservice will send an activation email to the address you specified.
7. Activate the account. Open the activation email, set a password, store it in your password manager, and complete first-time login.

Each Freshservice agent has a single API key tied to their account. The API key inherits the agent's role permissions, which is why we created dedicated read-only roles and a dedicated agent in steps 1 through 3.

1. Sign in as the integration agent. Use the credentials from step 3.
2. Open Profile Settings. Click your avatar in the top-right corner and select Profile Settings.
3. Locate the API Key section. It appears in the right-hand sidebar of the profile page.
4. Click View API Key or Copy. Freshservice may prompt you to re-enter the password or complete a verification step to reveal the key. The API key is a long alphanumeric string.
5. Record the API key securely. Copy it directly into your password manager or your organization's secrets vault. Do not paste it into chat, email, or unencrypted documents.

Before entering the key in the Info-Tech portal, confirm it can read tickets, reference objects, and the Freshservice ticket stats used by the integration.

1. Test basic ticket read. Run the following from a terminal, replacing YOUR_API_KEY with the key from step 4 and yourcompany with your Freshservice subdomain:

   curl -u YOUR_API_KEY:X -H "Content-Type: application/json" \
     "https://yourcompany.freshservice.com/api/v2/tickets?per_page=1"

   You should see a JSON response containing one ticket. If you get 401 Unauthorized, the key is wrong or the role lacks ticket access.
2. Test the stats include block. Run:

   curl -u YOUR_API_KEY:X -H "Content-Type: application/json" \
     "https://yourcompany.freshservice.com/api/v2/tickets?include=stats&per_page=1"

   The response should include a stats object on the ticket with fields such as first_responded_at, resolved_at, and closed_at. If the stats object is missing, flag this with your Info-Tech onboarding contact.
3. Test reference-table reads. Confirm each of these endpoints returns data:
   • /api/v2/agents
   • /api/v2/departments
   • /api/v2/locations
   • /api/v2/groups
   • /api/v2/sla_policies
   • /api/v2/roles
   • /api/v2/tickets/{ticket_id}/conversations (replace {ticket_id} with a ticket ID from the ticket-read test above)
   • /api/v2/tickets/{ticket_id}/time_entries (returns the worklog / time-tracking entries for that ticket — used for technician work-effort and cost-per-ticket reporting)
   • /api/v2/surveys/satisfaction_ratings (returns CSAT / satisfaction survey responses; the exact path can vary by tenant — if it 404s, confirm the satisfaction survey feature is enabled and flag it with your Info-Tech onboarding contact)
   If any return 403 Forbidden, the service account is missing the required view permission for that Freshservice object. Add the minimum read-only permission required, then test again.