Setting Up an API Key

Helpdocs Admin Updated by Helpdocs Admin

Who can create an API key

  • System-level API key — can only be created by a Master Admin.
  • Personal API key — can be created by an Agent. Personal API keys for Contacts aren't available in the UI yet, but support is planned for the future. In the meantime, use OAuth instead.

Creating a system-level API key

Go to Admin Portal → Advanced → API Keys to create one.

When creating a key, you'll need to provide:

  1. A name for the key, so you can identify it later.
  2. An expiration period — 7 days, 30 days, 60 days, 90 days, 1 year, or no expiration.
Recommendation: Avoid choosing 1 year or no expiration. Instead, set a short expiration and add a reminder (e.g., a calendar event) to renew the key and check in on how it's being used. Short-lived keys are safer — if a key is ever leaked, the exposure window is smaller.
For comparison, our OAuth implementation rotates its signing key every 7 days, and any single token is valid for a maximum of 5 weeks — giving it a much stronger security posture than a long-lived API key. OAuth will be covered in a separate set of articles.

Setting permissions (scopes)

The last step is choosing which scopes the API key should have — this determines exactly what it's allowed to query or modify.

Note: There used to be a "full access" option, but it's now deprecated. New API keys can no longer be created with full access, and any existing full-access keys will stop working by the end of 2027 (or possibly earlier).

Our scope selection UI is designed to make this straightforward, but to choose the right scopes for your integration:

  • Use Swagger to find the specific API endpoints you plan to call.
  • Check which scope each endpoint requires.
  • Only select the scopes you actually need.

A couple of shortcuts worth knowing:

  • Granting read_write for an entity automatically includes read access — you don't need to select both.
  • Choose the highest scope you need per entity, rather than selecting every scope individually.

"On behalf of" scopes

To create or manage tickets, comments, or time entries **as if a specific user had done it themselves**, an API key needs a combination of scopes:

  • The relevant resource scope — e.g., ticket:read_write and/or file:read_write.
  • Plus one of two standalone impersonation scopes:
    • agent:impersonate — act on behalf of an agent.
    • contact:impersonate — act on behalf of a contact.

You can grant one or both impersonation scopes depending on whether you need to act on behalf of agents, contacts, or both.

This combination is especially useful for MCP integrations or third-party UIs that need to perform actions under a real user's identity — for example, creating a ticket that shows as submitted by the actual contact, rather than by the integration itself.

"On behalf of" scopes are only available for system-level API keys, and currently apply to the ticket API (tickets, comments, time entries) and the files API — these are the only areas where impersonation is supported today.

Creating a personal API key

Agents can create their own personal API key from either:

  • Admin Portal, or
  • TECH Portal v2 → More → Settings → Personal API Keys

How did we do?

Using an API Key

Contact