Skip to main content
A valid token authenticates a caller. Each endpoint separately checks whether that caller can perform the requested action on the resource. Use Find endpoints to filter the API by your token type and permissions.

​
Public API keys

Exchange a public API key’s client ID and secret at Create token, then send the returned access token in the Authorization: Bearer ... header.
  • Organization-scoped keys can exercise their granted public API permissions across the organization.
  • Workspace-scoped keys have an allowed_team_ids restriction. Every workspace checked by the request must be on that allowlist. Organization-level and user-level checks fail even when the URL names an allowed workspace.
  • Permission bundles limit the actions a key can perform. Select the exact bundles granted to your key in the endpoint filter. A full-access key still has only the public API key permissions; it does not become a user token.
The token exchange follows OAuth2’s client-credentials flow, but the resulting token still represents an API key. In the endpoint filter, select API key, not OAuth.

​
User OAuth tokens

A user-delegated OAuth token acts as the user who authorized it. The endpoint must accept user identities, and the user must have the required permissions through their roles and resource access. Accepting OAuth does not make an endpoint available to every signed-in user. Some endpoints, such as status updates, require a user token and are unavailable to public API keys even with full access.

​
Request-specific checks

An endpoint can support several request forms with different requirements. The filter includes an endpoint when at least one form matches your selection; each endpoint page explains its request-specific requirements.
  • Permissions joined by + are all required. Or separates alternatives.
  • Publishing a workflow requires workflows:deploy as well as workflows:write. Saving a draft only needs the write permission.
  • Ticket archiving requires tickets:archive. Hard-delete requires tickets:admin; tickets:write grants neither.
  • With an API key, sharing a ticket with a ticket type role (role_id on Grant Ticket Access) requires tickets:grant-roles as well as tickets:write. With user OAuth, it requires permission to edit the ticket type.
  • Ticket and message searches without team_ids use an organization-level check. A workspace-scoped key must supply allowed workspace IDs.
  • Creating or listing approval delegations with an API key requires delegator_user_id. Omitting it selects the current user, and a key has no user identity.
  • Moving a ticket checks both the source and destination workspaces. One allowed workspace is insufficient.
  • Group ownership, entity sharing, ticket settings, and other resource rules can further restrict access.
  • A workspace-scoped key with groups:manage manages its allowed workspaces’ groups, much like a workspace manager in the app: it reads the groups those workspaces can see and can create, rename, delete, and change the members of the groups those workspaces manage. Creating a group takes a manager_team_id and can add only people, not agents, as members. A workspace-scoped key can’t rename or change the members of a group synced from a connected source, and it can’t change the members of or delete a group that grants a workspace role. Organization-scoped keys keep their existing access.
  • Deleting a group removes the group, its members, and its workspace-role bindings together. A group synced from a connected app can be deleted only after its source app is removed. Where SCIM group sync is enabled for the organization, a SCIM directory group can’t be renamed, have its members changed, or be deleted through the API. Its directory sync manages it.
The filter describes authorization requirements. It does not validate a live token or guarantee that a request will succeed. Expired or revoked credentials, missing resources, invalid parameters, and resource-specific checks can still reject a request.