Koppelen met de TOPdesk-API: account, rechten en testen

Met de REST-API van TOPdesk kan een ander systeem meldingen aanmaken, kaarten bijwerken of een wijziging starten vanuit een sjabloon. Het andere systeem logt in met een API-account en een applicatietoken. Wat het mag, regel je met een rechtengroep die past bij wat de koppeling doet.

Hieronder gaat het over koppelingen die iets in TOPdesk vastleggen of wijzigen. Wat de REST-API teruggeeft als je gegevens uitleest voor rapportage, en wat een foutmelding 401 of 403 betekent, lees je op aureadesk.com in Wat de TOPdesk-API wel en niet teruggeeft.

REST-API, webhook of actiereeks

TOPdesk heeft per onderdeel een eigen API, onder meer voor meldingen, wijzigingen, ondersteunende bestanden en assets. De documentatie staat op developers.topdesk.com. Volgens TOPdesk is de API gratis te gebruiken.

Een koppeling loopt via een van drie routes. Welke route past, hangt vooral af van welk systeem het initiatief neemt en van wat het andere systeem kan versturen of ontvangen.

Wat heb je nodig om met de TOPdesk-API te koppelen?

Een API-account (API account) is een serviceaccount. Het kan niet inloggen in het behandelaarsgedeelte, heeft geen persoonskaart nodig en telt in het Overzicht behandelaarslicenties (Operator licence overview) als gratis account. De koppeling logt in met een applicatietoken (application token) van het account en krijgt de juiste rechten via een rechtengroep. In TOPdesk SaaS richt je het account volgens de documentatie zo in:

1. API-account aanmaken: ga naar de modulepagina Ondersteunende bestanden en kies Nieuw > API-account (Supporting Files > New > API account). Vul een herkenbare naam, een vestiging en een inlognaam in, vink Heeft toegang aan en sla de kaart op.
2. Applicatietoken toevoegen: klik op de kaart onder Applicatietokens op Toevoegen, geef de toepassing een naam en kies een vervaldatum. Kopieer het token en bewaar het veilig, want TOPdesk toont het maar één keer. Om een token toe te voegen heb je zelf het recht Inloggegevens (schrijven) nodig.
3. Rechtengroep koppelen: wijs op het tabblad Autorisatie (Authorisation) een rechtengroep (permission group) toe met REST API > Lezen en Gebruik applicatietokens > Schrijven, plus de rechten voor de modules waar de koppeling mee werkt.
4. Inloggen vanuit het andere systeem: in de tutorial logt de koppeling in met Basic authentication, met de inlognaam als gebruikersnaam en het applicatietoken als wachtwoord.

TOPdesk raadt aan per functie een eigen API-account te gebruiken, met een herkenbare naam zoals ODATA-API of INCIDENT-ACTION-API. Je ziet dan in je eigen administratie waarvoor elk account dient, en TOPdesk Support kan de logboeken waar nodig efficiënter onderzoeken.

Rechten van het API-account

Geef een API-account alleen de rechten die de koppeling nodig heeft. TOPdesk geeft als voorbeeld een koppeling die een wijziging aanmaakt vanuit een sjabloon. Het account heeft dan het recht nodig om wijzigingen aan te maken en sjablonen te lezen.

Bij actiereeksen raadt TOPdesk aan de rechten te controleren door de taken eerst met de hand uit te voeren. Let daarbij op de vestigings-, categorie- en behandelaarsfilters op de behandelaarskaart, want de filters bepalen mee wat een behandelaar ziet en kan doen.

Meldingen en wijzigingen aanmaken via de API

In de tutorial van TOPdesk maakt een koppeling een melding aan met een POST-verzoek op /tas/api/incidents. Het verzoek bevat onder meer een aanmelder (caller), een behandelaar en een behandelaarsgroep. Een PUT-verzoek op een bestaande melding past daarna bijvoorbeeld de korte omschrijving aan.

Wijzigingen gaan op dezelfde manier, vanuit een wijzigingssjabloon en eventueel met een keuze uit de optionele activiteiten. TOPdesk voert de regels van het sjabloon uit. Keurt het sjabloon een aanvraag automatisch goed, dan wordt ook een wijziging die via de API binnenkomt automatisch goedgekeurd.

TOPdesk meldt in de community (21 april 2026) dat API-accounts sinds One TOPdesk User niet meer in keuzelijsten verschijnen, ook niet bij het kiezen van een aanmelder. Spreek daarom vooraf af wie als aanmelder op een melding van een systeem komt te staan.

Laat je een monitoringpakket meldingen aanmaken, stel het pakket dan zo in dat het per verstoring één verzoek stuurt. In het voorbeeld van TOPdesk heeft een server nog weinig vrije schijfruimte. Dan hoort er één verzoek naar TOPdesk te gaan, niet elke vijf seconden hetzelfde.

Wanneer gebruik je een webhook in plaats van de API?

Bij een webhook stuurt het andere systeem een verzoek naar een eigen adres in TOPdesk. Het verzoek start een e-mail, een document of een actiereeks, en in de actie kun je velden uit het bericht gebruiken. Een webhook past als je de opmaak van de berichten uit het andere systeem niet in de hand hebt.

Een webhook maak je onder Modules > Actiebeheer > Geautomatiseerde acties > Nieuwe geautomatiseerde actie > Webhooks en geplande acties (Modules > Action Management > Automated Actions > New automated action > Webhooks and scheduled actions). Het verzoek uit het andere systeem heeft een autorisatieheader met inloggegevens nodig. Volgens de documentatie over webhooks gaat het om een behandelaar met het recht Webhooks activeren; een apart API-account noemt de documentatie niet. Met een vinkje bepaal je of de aanvraagtekst (request body) van elk verzoek in de uitvoeringslogs komt. TOPdesk raadt aan het vinkje eerst te laten staan. Kan er gevoelige informatie in een verzoek staan, dan kun je het vinkje uitzetten.

Testen zonder productie te raken

Heb je een testomgeving, bouw en test de koppeling dan daar. TOPdesk noemt als veelvoorkomend probleem een actiereeks in test die nog naar productie verwijst, zodat een test gegevens in productie wijzigt.

Let ook op lussen. Werkt een actiereeks via de API een kaart bij en reageert een gebeurtenis op elke bewerking, dan kan de actiereeks zichzelf opnieuw starten. TOPdesk heeft een beveiliging tegen lussen, maar raadt aan de gebeurtenis niet te laten afgaan als de wijziging komt van het API-account dat de actie gebruikt. Hoe je actiereeksen test en beschrijft, lees je in Gebeurtenissen en acties in TOPdesk.

Veranderingen in 2026

Hieronder staat de stand in oktober 2026, op basis van wat TOPdesk publiceert.

• OAuth 2.0: TOPdesk meldt in de community (13 augustus 2026) dat koppelingen ook met OAuth 2.0 kunnen inloggen, met toegangstokens die na korte tijd verlopen. Voor OAuth 2.0 maak je een integratieclient (integration client) aan. Bestaande API-accounts en applicatietokens blijven werken, en overstappen is volgens TOPdesk niet verplicht.
• One TOPdesk User: TOPdesk meldt in de community (21 april 2026) dat de persoonskaart leidend wordt en dat de verandering koppelingen kan raken.
• 23 november 2026: TOPdesk meldt in de community (22 mei 2026) dat het vanaf 23 november 2026 een aantal functies uitschakelt. De lijst staat in KI 19238 op My TOPdesk. Hoe TOPdesk de uitfasering aankondigde, lees je in TOPdesk-releases bijhouden. Ga na of een koppeling iets gebruikt wat op de lijst staat.

Beheer van de koppeling

Leg per koppeling vast wie de eigenaar is, welk account de koppeling gebruikt en wanneer het token verloopt. Een applicatietoken verloopt volgens de tutorial van TOPdesk standaard een jaar na het aanmaken. Is het token verlopen, dan kan de koppeling niet meer inloggen en maak je een nieuw token aan. Wat je verder vastlegt als de beheerder vertrekt, lees je in Functioneel beheerder TOPdesk vertrekt.

Behandel een token als een wachtwoord en deel het niet via e-mail, chat of versiebeheer. TOPdesk geeft hetzelfde advies voor de Client-ID en het clientgeheim van een integratieclient. Lees bij elke update de API-releasenotes mee, waarin TOPdesk per release de wijzigingen in de API beschrijft.

Wij bouwen koppelingen tussen TOPdesk en andere systemen, ook met webhooks en actiereeksen, van een eenmalige import tot een doorlopende synchronisatie. Een voorbeeld uit ons werk is een koppeling tussen twee TOPdesk-omgevingen, waarbij meldingen en wijzigingen heen en weer gaan en statussen en andere velden op elkaar zijn afgestemd. Op de pagina TOPdesk-consultancy staat meer over koppelingen via de API.