Inleiding
Met de Salesdock API kun je gegevens uit Salesdock ophalen, aanmaken of bijwerken vanuit een extern systeem — bijvoorbeeld een CRM, ERP, BI-tool of een eigen integratie. Voor authenticatie heb je een API token nodig dat is gekoppeld aan een gebruiker in jouw account. De rechten van die gebruiker bepalen wat de koppeling mag doen, dus is het essentieel om dit zo beperkt mogelijk in te stellen.
Dit artikel beschrijft:
- Een aparte gebruiker aanmaken voor de koppeling
- De juiste rol kiezen
- Rechten verfijnen via Beheer rechten
- Het API token genereren
- Beveiligingsopties instellen en het token opslaan
- Operationele aandachtspunten
- Veelgestelde vragen
Volledige technische documentatie — endpoints, voorbeelden en authenticatie in detail — vind je op developer.salesdock.nl. Dit artikel beschrijft alleen het aanmaken en beveiligen van de API key in de Salesdock-interface.
1. Maak een aparte gebruiker aan voor de koppeling
Gebruik nooit een persoonlijk account voor een integratie. Door een dedicated gebruiker aan te maken kun je later onafhankelijk van een medewerker rechten beheren of intrekken.
- Ga naar Account → Gebruikers.
- Maak een nieuwe gebruiker aan met een herkenbare naam, bijvoorbeeld
Koppeling-CRMofKoppeling-Facturatie. Vermijd spaties zodat de naam in logs en URL's goed leesbaar blijft.
2. Kies de juiste rol
De rol die je deze gebruiker geeft bepaalt direct het bereik van het API token:
| Rol | Bereik | Wanneer kies je dit? |
|---|---|---|
| Agent | User scope — alleen toegang tot data die aan deze gebruiker is toegewezen. | Een koppeling die per agent leads of taken ophaalt en bijwerkt. |
| Admin | Account scope — toegang tot data binnen het hele account, binnen de grenzen van de toegekende rechten. | Een BI-koppeling die alle sales naar een datawarehouse exporteert, of een master-integratie die accountbreed leest en schrijft. |
Vuistregel: kies de kleinste scope die voldoet. Een koppeling die alleen leads leest, hoeft geen Admin-rechten te hebben.
3. Verfijn de rechten via Beheer rechten
Naast de rol kun je per module aangeven wat de gebruiker precies mag. Open het detailscherm van de gebruiker en klik op Beheer rechten. Schakel alleen die rechten in die de koppeling daadwerkelijk nodig heeft.
Een koppeling die alleen leads ophaalt en aanmaakt, hoeft geen schrijfrechten op transacties of klanten. Door deze rechten beperkt te houden voorkom je dat een gelekt token meer schade kan aanrichten dan strikt nodig.
4. Genereer het API token
- Ga in het gebruikersoverzicht naar de gebruiker die je zojuist hebt aangemaakt.
- Klik aan de rechterkant op Acties → API Token → Genereer.
- In het pop-upscherm wordt een uniek token getoond. Dit token is daarna niet meer zichtbaar, dus zorg dat je hem direct kopieert in stap 5.
5. Beveiligingsopties instellen en token opslaan
In het pop-upscherm zie je twee schakelaars en een knop om op te slaan. Doorloop ze in deze volgorde:
5a. Token kopiëren
Klik op Kopiëren en plak het token meteen in een veilige plek — een password manager (bijvoorbeeld Bitwarden of 1Password) of de secrets-store van je integratieplatform. Behandel het token als een wachtwoord: nooit in een git-repository plaatsen, nooit in client-side code (browser, mobiele app) opnemen.
5b. "Wordt deze API token gebruikt voor een Salesdock-integratie?" — LATEN UITSTAAN
Deze schakelaar is bedoeld voor interne Salesdock-naar-Salesdock integraties (provider/consumer-koppelingen tussen Salesdock-accounts). Voor een externe koppeling die jij zelf bouwt of laat bouwen moet deze toggle uit blijven staan.
Let op: staat deze schakelaar per ongeluk aan, dan wordt elk verzoek vanaf je eigen server geweigerd met de foutmelding
403 — API token is only available for Salesdock internal integration. Genereer in dat geval een nieuw token met de schakelaar uit.
5c. IP-restrictie inschakelen (sterk aanbevolen)
Zet IP-restrictie inschakelen aan en voer in het tekstveld het publieke IP-adres van je integratieserver in. Eén IP per regel als er meerdere zijn. Verzoeken vanaf andere IP's worden door de API geweigerd. Dit beperkt de schade aanzienlijk als het token onverhoopt zou lekken.
5d. Klik op "Sla token op"
Dit is de afsluitende stap die het token daadwerkelijk activeert. Sluit je het scherm zonder op Sla token op te klikken, dan is het token niet bruikbaar — ook al heb je hem al gekopieerd.
6. Operationele aandachtspunten
Rate limiting
De API limiteert het aantal verzoeken per gebruiker tot 150 per minuut. Bij overschrijding krijg je een HTTP 429 Too Many Requests-respons. Bouw in je integratie een retry-mechanisme met exponential backoff zodat pieken netjes worden afgehandeld.
Token-rotatie
API tokens vervallen niet automatisch. Roteer ze actief op een vast interval (bijvoorbeeld elke 6 tot 12 maanden) of zodra een medewerker met kennis van het token het bedrijf verlaat. Werkwijze: genereer een nieuw token op dezelfde gebruiker, deploy het in je integratie en verwijder daarna het oude token via Acties → API Token.
Token intrekken bij compromittering
Vermoed je dat het token is gelekt? Ga direct naar Account → Gebruikers → [gebruiker] → Acties → API Token en kies Verwijder (of genereer een nieuw token, waarmee het oude vervalt). Werk je integratie meteen daarna bij met het nieuwe token.
Wat als de API-gebruiker wordt gedeactiveerd of verwijderd?
Het bijbehorende token wordt dan automatisch ongeldig. Deactiveer een API-gebruiker dus nooit "voor de zekerheid" — je integratie valt dan stil. Wil je tijdelijk de toegang opheffen? Verwijder dan liever het token zelf en genereer een nieuwe wanneer je weer toegang wilt verlenen.
7. Probleemoplossing
| Foutmelding / situatie | Vermoedelijke oorzaak | Oplossing |
|---|---|---|
403 Forbidden | IP-restrictie blokkeert het verzoek — je integratieserver belt vanaf een ander IP dan op de allow-lijst staat. | Controleer het publieke IP van je server en voeg het toe aan de allow-lijst, of test tijdelijk zonder IP-restrictie om de oorzaak te bevestigen. |
403 — API token is only available for Salesdock internal integration | De schakelaar "Wordt deze API token gebruikt voor een Salesdock-integratie?" stond aan toen het token werd aangemaakt. | Genereer een nieuw token, met deze schakelaar uit. Werk je integratie bij met het nieuwe token. |
| Token werkt niet, ook niet meteen na aanmaken | Op Sla token op is niet geklikt na het kopiëren. | Genereer een nieuw token en sluit de flow expliciet af met Sla token op. |
429 Too Many Requests | De rate limit van 150 verzoeken per minuut is bereikt. | Bouw retry-with-backoff in je client. Spreid grote bulkacties over meer tijd of overweeg om meerdere integraties te splitsen over meerdere gebruikers. |
| Token werkte tot voor kort, nu niet meer | De API-gebruiker is gedeactiveerd of verwijderd. | Reactiveer de gebruiker en genereer indien nodig een nieuw token. Communiceer met je team dat API-gebruikers niet "voor de zekerheid" moeten worden gedeactiveerd. |
8. Veelgestelde vragen
Mag ik één token gebruiken voor meerdere integraties?
Technisch kan het, maar we raden het af. Maak per integratie een eigen gebruiker en een eigen token aan. Zo kun je één integratie intrekken zonder de andere te raken, en in audit-logs is meteen duidelijk welke integratie welke actie uitvoerde.
Verloopt een API token automatisch?
Nee, tokens blijven geldig totdat je ze actief verwijdert. Daarom adviseren we ze periodiek te roteren (zie sectie 6).
Kan ik bestaande tokens van een gebruiker terugzien?
Het tokenwaarde zelf is na aanmaken niet meer zichtbaar — bewaar hem dus altijd direct in een password manager. Wel kun je via Acties → API Token zien of er een token bestaat, de IP-restrictie aanpassen en het token verwijderen of regenereren.
Wat is het verschil tussen IP-restrictie per token en de account-brede IP-whitelist?
De IP-restrictie per token (sectie 5c) geldt alleen voor dat ene token. De account-brede IP-whitelist — in te stellen via Account → Beveiliging → IP-whitelisting wanneer voor jouw account beschikbaar — geldt voor alle UI- en API-toegang tot het account. Voor de meeste integraties is de per-token-instelling voldoende; de account-brede whitelist is een extra laag voor compliance.
Wat moet ik doen als mijn integratiepartner een eigen API key vraagt?
Maak voor de partner een aparte gebruiker met een herkenbare naam (bijv. Koppeling-PartnerNaam), kies de minimaal benodigde rol en rechten, genereer het token en deel het via een veilig kanaal (password manager met share-functie). Deel nooit een bestaande token van een andere integratie.
Korte begrippenlijst
API token — De sleutel waarmee een externe applicatie zich bij de Salesdock API authenticeert. Gekoppeld aan één gebruiker.
Scope — Het bereik van een token. Bepaald door de rol van de gebruiker (Agent = user scope, Admin = account scope).
IP-restrictie — Een lijst van toegestane IP-adressen waar het token vandaan mag bellen. Verzoeken vanaf andere IP's worden geweigerd.
Rate limit — Maximumaantal API-verzoeken per tijdseenheid. Momenteel 150 verzoeken per minuut per gebruiker.
Salesdock-integratie schakelaar — Interne modus voor tokens die binnen Salesdock-eigen provider/consumer-koppelingen worden gebruikt. Voor externe koppelingen altijd uit laten.