De REST API van Xcellerate OPS gebruiken met persoonlijke API-sleutels

Xcellerate OPS heeft een gedocumenteerde REST API (v1). Daarmee koppel je je eigen tools, scripts of automatiseringsplatformen aan tickets, bedrijven, contacten, deals, projecten, tijdregistraties, assets en meer. Elke gebruiker maakt zijn eigen API-sleutels aan in zijn profiel, en een sleutel kan precies wat die gebruiker in de app kan, niet meer. Deze gids is voor technische beheerders bij MSP's en dienstverlenende kmo's.

TL;DR

• Maak een sleutel aan in je profiel onder API keys en kopieer het token meteen: het wordt maar één keer getoond.
• Stuur bij elk verzoek twee headers mee: Authorization: Bearer <token> en X-Tenant-Id.
• Een sleutel erft de rechten van je gebruiker. Standaard mag je 120 verzoeken per minuut per sleutel doen.

Voor je begint

• Elke medewerker kan voor zichzelf sleutels aanmaken. Je hebt daarvoor geen adminrol nodig.
• Wat een sleutel mag, volgt één op één je teamrechten. Wat in de app geblokkeerd is, is ook in de API geblokkeerd.
• Je hebt een HTTP-client die headers kan meesturen: een script, een automatiseringsplatform of je eigen applicatie.
• Je kan maximaal 20 actieve sleutels per gebruiker hebben.

Let op: de sectie voor API-sleutels is in de app alleen in het Engels beschikbaar. De labels hieronder staan daarom in het Engels.

Een API-sleutel aanmaken en gebruiken

Stap 1: open je API-sleutels

Ga naar je profiel en open de sectie API keys.

Stap 2: maak de sleutel aan

Geef de sleutel een naam die zegt waarvoor hij dient. Kies of hij alleen mag lezen of ook mag schrijven, en stel eventueel een vervaldatum in die in de toekomst ligt. Sleutels zijn alleen-lezen, tenzij je ze met schrijfrechten aanmaakt. Heb je enkel gegevens nodig, kies dan alleen-lezen.

Stap 3: kopieer het token

Na het aanmaken toont OPS de melding "Copy your new API key now — it will not be shown again." Kopieer het token meteen en bewaar het veilig. Tokens beginnen met xok_. Ben je het kwijt, maak dan een nieuwe sleutel aan.

Stap 4: kopieer je werkruimte-ID

In dezelfde sectie staat de ID van je werkruimte. Kopieer die met de knop Copy. Je hebt ze bij elk verzoek nodig.

Stap 5: doe een eerste verzoek

Test je sleutel met een eenvoudig verzoek naar /api/v1/me, met beide headers:

GET /api/v1/me
Authorization: Bearer <token>
X-Tenant-Id: <workspace id>

De link API documentation ↗ in de sectie opent de interactieve documentatie. Controleer daar het juiste basisadres en de beschikbare endpoints.

Stap 6: trek sleutels in die je niet meer gebruikt

Je trekt een sleutel in vanuit dezelfde lijst. Per sleutel zie je wanneer hij het laatst gebruikt is, zo spot je snel sleutels die niemand meer nodig heeft.

Wat er gebeurt na het koppelen

• Formaat: JSON voor verzoeken en antwoorden. Lijsten zijn gepagineerd met een cursor.
• Bereik: onder meer bedrijven, contacten, CRM-interacties, aangepaste velden, tickets en ticketplanningen, projecten met planning en financiën, tijdregistraties, onkosten, afwezigheden, werktijd, assets en CMDB, software, diensten, changes, problems, major incidents, releases, kennisbank, opportuniteiten, tariefkaarten, terugkerende facturen, rapporten, SLA- en XLA-rapporten, oproepen en opnames en het logboek van AI-acties. De volledige lijst staat in de API-documentatie.
• Klantportaal: klanten die je klantportaal gebruiken, kunnen er hun eigen sleutels aanmaken. Die zien alleen hun eigen gegevens.

Meer over hoe OPS toegang afschermt, lees je bij beveiliging en toegangsbeheer. Een overzicht van alle koppelingen vind je bij EU-integraties en beveiliging.

Goed om te weten

• Limiet: standaard 120 verzoeken per minuut per sleutel. RMM Labs kan dat op aanvraag verhogen voor een werkruimte. Elk antwoord bevat de headers X-RateLimit-Limit en X-RateLimit-Remaining.
• Mislukte aanmeldingen: herhaalde mislukte aanmeldingen vanaf hetzelfde adres worden tijdelijk geblokkeerd.
• Sleutels horen bij een persoon. Schakel je een gebruiker uit, dan worden zijn sleutels ingetrokken en geblokkeerd. Koppelingen die op die sleutels draaien, stoppen dan. Hou daar rekening mee bij het vertrek van een medewerker.
• Persoonlijke instellingen, zoals voorkeuren voor agendasynchronisatie, zijn niet beschikbaar via de API.

Probleemoplossing

• 401 unauthenticated "Invalid API credentials." Het token is fout, vervallen of ingetrokken, de X-Tenant-Id ontbreekt of klopt niet, de werkruimte is opgeschort of de gebruiker is uitgeschakeld. Al die gevallen geven bewust hetzelfde antwoord.
• 429 rate_limited "Too many requests." Wacht het aantal seconden uit de header Retry-After.
• 429 "Too many failed authentication attempts." Je IP-adres is tijdelijk geblokkeerd na te veel mislukte pogingen.
• "You have reached the maximum number of API keys." Je hebt 20 actieve sleutels. Trek er eerst een in.

Aan de slag

Wil je OPS koppelen aan je eigen scripts en tools? Start gratis en maak je eerste API-sleutel aan in je profiel.