Wat is een API-sleutel?

Wat het is

een wachtwoord voor software

Geeft toegang tot

alles wat de gebruiker mag zien

Regel

een eigen gebruiker per koppeling

De definitie in gewone taal

Een API-sleutel is een lange, unieke code waarmee software zich bij Pipedrive identificeert. De afkorting API staat voor application programming interface. Dat is de ingang waarlangs programma's met elkaar praten, zonder dat er iemand op een knop drukt.

Vergelijk het met een sleutel van je kantoor. Wie hem heeft, komt binnen. De sleutel weet niet wie hem gebruikt en vraagt geen wachtwoord. Daarom is het meesturen van zo'n code precies zo gevoelig als het delen van je inloggegevens.

Belangrijk detail: de sleutel hangt aan een gebruiker. Hij ziet dus exact wat die gebruiker mag zien en mag exact wat die gebruiker mag doen. Heeft die gebruiker beheerrechten, dan kan de koppeling ook instellingen wijzigen en gegevens verwijderen. Welke rechten iemand krijgt, regel je in rechten en zichtbaarheid.

Waarom het ertoe doet

Een verkeerd geplaatste sleutel is een echt risico. Een voorbeeld dat we vaker zien dan ons lief is. Een ontwikkelaar zet de sleutel in de code van een website, zodat het contactformulier direct een lead kan aanmaken. Die code staat in de browser van elke bezoeker. Iedereen kan hem dus uitlezen.

Vanaf dat moment kan een buitenstaander je hele klantenbestand ophalen. Bij twaalfduizend contactpersonen is dat een datalek dat je binnen tweeënzeventig uur moet melden. De boetes laten we hier buiten beschouwing. Alleen de opschoning en de communicatie kosten al snel een paar dagen werk.

Er is ook een minder dramatische, maar veelvoorkomende reden. Koppelingen die op de persoonlijke sleutel van een medewerker draaien, vallen uit zodra die medewerker vertrekt. Meestal ontdek je dat pas weken later, als blijkt dat er geen facturen meer zijn aangemaakt. Een aparte koppelingsgebruiker voorkomt dat volledig.

Zo gebruik je hem in Pipedrive

Je vindt je sleutel onder je persoonlijke voorkeuren, bij het onderdeel voor de API. Vier regels houden het netjes.

• Maak een aparte gebruiker aan voor koppelingen, bijvoorbeeld met een mailadres van je bedrijf. Geef hem alleen de rechten die de koppeling echt nodig heeft.
• Bewaar de sleutel in de kluis van je automatiseringstool of in een wachtwoordmanager. Nooit in een spreadsheet, een chatbericht of de code van je website.
• Gebruik voor kant-en-klare apps de OAuth-koppeling als die er is. Dan kun je toegang per app intrekken zonder al je andere koppelingen te breken.
• Laat berichten vanaf je website altijd langs een tussenlaag lopen, zoals beschreven in Pipedrive koppelen aan je website. De sleutel blijft dan op de server.

Werk je met Make of Zapier, dan leg je de sleutel één keer vast in de verbinding. Alle scenario's gebruiken die verbinding daarna opnieuw. Dat scheelt beheer en het beperkt het aantal plekken waar de code staat.

Houd tot slot rekening met de limieten. Pipedrive begrenst het aantal aanroepen per seconde en per dag. Trekt één koppeling die limiet leeg, dan lopen je andere koppelingen vertraging op. Verdeel zwaar werk daarom over de nacht en meet hoeveel aanroepen je scenario's per dag doen.

Waar het misgaat

De eerste fout is de sleutel op de verkeerde plek zetten. In de browser, in een openbare map met code of in een gedeeld document. Vuistregel: alles wat een bezoeker kan opvragen, is openbaar. Houd de sleutel dus altijd op je server of in een beheerde kluis.

De tweede fout is te ruime rechten. Een koppeling die alleen deals aanmaakt, heeft geen beheerrechten nodig. Geef standaard het minimum en breid pas uit als iets echt niet werkt. Zo blijft de schade beperkt als er ooit iets misgaat.

De derde fout is niets bijhouden. Na twee jaar weet niemand meer welke koppeling welke sleutel gebruikt. Houd een eenvoudige lijst bij met per koppeling het doel, de gebruiker en de eigenaar. Loop die lijst elk half jaar langs en zet uit wat niemand meer gebruikt. Doe dat ook bij de webhooks die je hebt ingesteld.

Veelgestelde vragen