TOPdesk API integrations: account, permissions and testing

With the TOPdesk REST API, another system can create calls, update cards or start a change from a template. The other system logs in with an API account and an application token. You set what it may do with a permission group that matches what the integration does.

The sections below cover integrations that record or change something in TOPdesk. What the REST API returns when you read data for reporting, and what a 401 or 403 error means, is covered on aureadesk.com in What the TOPdesk API does and does not return.

REST API, webhook or action sequence

TOPdesk has a separate API for each part of the application, including calls, changes, Supporting Files and assets. The documentation is at developers.topdesk.com. According to TOPdesk, the API is free to use.

An integration follows one of three routes. Which route fits depends mainly on which system takes the initiative and on what the other system can send or receive.

What do you need to integrate with the TOPdesk API?

An API account is a service account. It cannot log in to the Operator Section, needs no person card and counts as a free account in the Operator licence overview. The integration logs in with an application token from the account and gets the right permissions through a permission group. According to the documentation, you set up the account in TOPdesk SaaS as follows:

1. Create the API account: go to the Supporting Files module page and choose New > API account. Fill in a recognisable name, a branch and a login name, tick Has access and save the card.
2. Add an application token: on the card, under Application tokens, click Add, give the application a name and choose an expiry date. Copy the token and store it securely, because TOPdesk shows it only once. To add a token, you need the Login data (write) permission yourself.
3. Assign a permission group: on the Authorisation tab, assign a permission group with REST API > Read and Use application tokens > Write, plus the permissions for the modules the integration works with.
4. Log in from the other system: in the tutorial, the integration logs in with Basic authentication, using the login name as the username and the application token as the password.

TOPdesk recommends using a separate API account for each function, with a recognisable name such as ODATA-API or INCIDENT-ACTION-API. Your own administration then shows what each account is for, and TOPdesk Support can investigate the logs more efficiently where needed.

Permissions of the API account

Give an API account only the permissions the integration needs. TOPdesk gives the example of an integration that creates a change from a template. The account then needs the permission to create changes and to read templates.

For action sequences, TOPdesk recommends checking the permissions by first carrying out the tasks by hand. When doing so, pay attention to the branch, category and operator filters on the operator card, because the filters partly determine what an operator can see and do.

Creating calls and changes through the API

In TOPdesk's tutorial, an integration creates a call with a POST request to /tas/api/incidents. The request includes a caller, an operator and an operator group, among other things. A PUT request on an existing call then changes the brief description, for example.

Changes work the same way, from a change template and, if needed, with a choice of the optional activities. TOPdesk applies the rules of the template. If the template approves a request automatically, a change that comes in through the API is approved automatically as well.

TOPdesk announced in the community (21 April 2026) that since One TOPdesk User, API accounts no longer appear in drop-down lists, including when you select a caller. Agree in advance, therefore, who will be the caller on a call that comes from a system.

If a monitoring tool creates calls, configure it to send one request per disruption. In the example TOPdesk gives, a server is running low on free disk space. One request should then go to TOPdesk, not the same one every five seconds.

When do you use a webhook instead of the API?

With a webhook, the other system sends a request to a dedicated address in TOPdesk. The request starts an email, a document or an action sequence, and in the action you can use fields from the message. A webhook fits when you have no control over the format of the messages from the other system.

You create a webhook under Modules > Action Management > Automated Actions > New automated action > Webhooks and scheduled actions. The request from the other system needs an Authorization header with credentials. According to the documentation on webhooks, these are the credentials of an operator with the Trigger webhooks permission; the documentation does not mention a separate API account. A checkbox determines whether the request body of each request goes into the execution logs. TOPdesk advises leaving the checkbox ticked at first. If a request may contain sensitive information, you can untick it.

Testing without touching production

If you have a test environment, build and test the integration there. One common issue TOPdesk describes is an action sequence in test that still points to production, so that a test changes data in production.

Also watch out for loops. If an action sequence updates a card through the API and an event responds to every edit, the action sequence can start itself again. TOPdesk has a safeguard against loops, but recommends not letting the event fire when the change comes from the API account the action uses. How to test and document action sequences is covered in Events and actions in TOPdesk.

Changes in 2026

The points below reflect the situation in October 2026, based on what TOPdesk publishes.

• OAuth 2.0: TOPdesk announced in the community (13 August 2026) that integrations can also log in with OAuth 2.0, using access tokens that expire after a short time. For OAuth 2.0 you create an integration client. Existing API accounts and application tokens keep working, and according to TOPdesk, switching is not mandatory.
• One TOPdesk User: TOPdesk announced in the community (21 April 2026) that the person card is becoming the leading card and that the change may affect integrations.
• 23 November 2026: TOPdesk announced in the community (22 May 2026) that it will switch off a number of features from 23 November 2026. The list is in KI 19238 on My TOPdesk. How TOPdesk announced the phase-out is covered in Keeping up with TOPdesk releases. Check whether an integration uses anything on the list.

Managing the integration

For each integration, record who owns it, which account it uses and when the token expires. According to TOPdesk's tutorial, an application token expires one year after creation by default. Once the token has expired, the integration can no longer log in and you create a new token. What else to record when the administrator leaves is covered in TOPdesk administrator leaving.

Treat a token like a password and do not share it through email, chat or version control. TOPdesk gives the same advice for the Client ID and client secret of an integration client. With every update, also read the API release notes, in which TOPdesk describes the changes to the API for each release.

We build integrations between TOPdesk and other systems, including with webhooks and action sequences, from a one-off import to continuous synchronisation. An example from our work is an integration between two TOPdesk environments, in which calls and changes pass back and forth and statuses and other fields are aligned with each other. You can read more about integrations through the API on the TOPdesk consultancy page.