How to Connect to Freshservice

Connecting Freshservice takes two values from your own Freshservice account: your subdomain and your personal API key.

Prerequisites

• A Freshservice agent account on your organization's Freshservice tenant.
• Permission to view tickets with that account. Your API key inherits your own agent permissions, and the connection check reads your ticket list (see Locate your API key).

No special administrator role is documented as a requirement for generating the key — the key inherits your own agent permissions.

1. Find your subdomain

Your subdomain is the part of your Freshservice URL before .freshservice.com. If you sign in at https://mycompany.freshservice.com, your subdomain is mycompany.

Enter only the bare subdomain in Vault. The form already shows the https:// prefix and the .freshservice.com suffix around the field, so typing the full URL produces an invalid address.

You sign in at	Enter in the Subdomain field
https://mycompany.freshservice.com	mycompany
https://acme-it.freshservice.com/a/tickets	acme-it

If your organization reaches Freshservice through a vanity or custom domain, use the Freshservice-issued .freshservice.com address instead — the Freshservice API v2 only accepts Freshservice-issued domains.

2. Locate your API key

1. Sign in to your Freshservice Support Portal at https://{your-subdomain}.freshservice.com.
2. Click your profile picture in the top-right corner.
3. Select Profile settings.
4. Your API key appears in the sidebar on the right of that page.

For the vendor's own walkthrough, see Where do I find my API key? and the Freshservice API documentation.

What the key can access. The key carries exactly the permissions of the agent who generated it — no more, no less. Because the connection is verified by listing tickets, generate the key from an account that can view tickets. If you need the connection to reach a wider set of records later, generate it from an agent account with the access those records require.

Use the API key, not your Freshservice password: Freshservice retired username-and-password API authentication on 2023-05-31, and the API key is now the only credential the API accepts.

3. Connect in Vault

1. Open the Freshservice connection in Vault.
2. Subdomain — enter the bare subdomain from step 1 (for example mycompany).
3. API Key — paste the key from step 2. The field is masked once saved.
4. Click Save.

Saving runs the check immediately: Apideck calls GET /api/v2/tickets on your tenant with your key. When it succeeds, the connection is marked as connected.

Your Freshservice account is now connected 🎉.

Troubleshooting

"Invalid credentials" or the connection fails right after saving. The two most common causes, in order:

1. The Subdomain field contains more than the bare subdomain. Remove https://, .freshservice.com, and any trailing path — mycompany is the whole value.
2. The API key was copied incompletely, or with leading/trailing whitespace. Re-copy it from Profile settings and paste it again.

Also confirm you pasted the API key rather than your account password — password authentication is no longer accepted.

The subdomain and key are both right, but validation still fails. Check that the agent account whose key you used can open the ticket list in Freshservice itself. If that account cannot view tickets, the check fails even though the key is valid. Either use a key from an account with ticket access, or ask your Freshservice administrator to grant ticket-view permission to the account you are using.

The connection worked and later stopped. An API key stops working if the agent account is deactivated or has its permissions reduced, or if the key stored in Vault is no longer the one active on that account. Open Profile settings in Freshservice to retrieve the key shown there — see Where do I find my API key? — and save it in Vault again.

Requests return HTTP 429. You have hit a Freshservice rate limit. The response includes a Retry-After header telling you how many seconds to wait before retrying. For the limits that apply to your plan, see What is the rate limit for APIs across all plans?. Note that failed and invalid requests count toward the limit too, so retrying immediately in a loop makes the throttling last longer.

Still stuck? Contact Apideck Support.