17. Integratie-API en API-sleutels

Met de integratie-API kan je eigen programma, spreadsheet of script de gegevens van je projecten machinaal uitlezen: de projectlijst, de kabel- en materiaallijsten, de groepenlijst en de klemmenlijst van de verdeelkasten, de hoeveelhedenstaat en de samenstelling van het tekenpakket. De API is alleen-lezen: ze wijzigt de tekening en het project niet.

Wie kan een API-sleutel krijgen

De API-sleutel wordt per account door de beheerder toegestaan. Als je account toestemming heeft gekregen, verschijnt op de pagina Profiel de kaart API-sleutels; zonder toestemming is de kaart niet zichtbaar. Een account kan maximaal 5 actieve sleutels tegelijk hebben.

De sleutel ziet dezelfde projecten als jij: je eigen projecten en, op verzoek, die welke met je zijn gedeeld. De lijsten en de hoeveelhedenstaat van een gedeeld project worden alleen verstrekt als de deling ook exporteren toestaat.

Een sleutel aanmaken

1. Klik op de kaart API-sleutels van de pagina Profiel op de knop Nieuwe sleutel.
2. Geef de sleutel een naam (bijvoorbeeld de naam van het programma dat hem gaat gebruiken).
3. Kies het bereik: Projecten lezen geeft de projectlijst en de projectgegevens, Documenten lezen geeft de lijsten, de hoeveelhedenstaat en het tekenpakket. Geef alleen op wat het programma echt nodig heeft.
4. Kies de geldigheidsduur: 30, 90 of 365 dagen. Een verlopen sleutel werkt niet meer; je maakt dan een nieuwe aan.
5. Voer je huidige wachtwoord in (bij een account zonder wachtwoord is een verse aanmelding nodig). Accepteer bij de eerste sleutel de voorwaarden voor API-gebruik.

Na het aanmaken is de sleutel slechts één keer zichtbaar: kopieer hem en bewaar hem op een veilige plek. Later toont de lijst alleen het voorvoegsel (avk_…), met de datum van aanmaak en verloop, het laatste gebruik en het aantal aanroepen. Over de nieuwe sleutel sturen we ook een e-mailmelding (zonder de sleutel zelf).

Een sleutel intrekken

Met de knop Intrekken naast de sleutel op de kaart wordt de sleutel onmiddellijk onbruikbaar; dit kan niet ongedaan worden gemaakt. Trek de sleutel in als je hem niet meer gebruikt, als je het programma dat hem gebruikte opheft, of als je vermoedt dat hij is uitgelekt.

Beveiligingstips

• Behandel de sleutel als je wachtwoord: wie hem kent, kan binnen het opgegeven bereik je projecten lezen.
• Bewaar hem in een geheimenopslag (wachtwoordbeheerder, omgevingsvariabele van de server of geheime variabele van de CI), niet in de broncode: zet hem niet in de git-repository, in een gedeelde spreadsheet of in een e-mail.
• Gebruik hem niet in code die in de browser draait (webpagina, browserextensie): daar kan iedereen hem uitlezen. Een sleutel hoort op een server, in een script of in een desktopprogramma.
• Geef elk programma een eigen sleutel met een zo smal mogelijk bereik en een korte geldigheid; zo legt het intrekken van één sleutel niets anders stil.

Gebruik vanuit een programma

In de kop van het verzoek wordt de sleutel als Bearer-token meegestuurd: Authorization: Bearer avk_…. De eindpunten staan onder /api/v1/ (bijvoorbeeld GET /api/v1/projects) en het antwoord is JSON. De exacte beschrijving in OpenAPI-formaat is beschikbaar op /api/v1/openapi.json; de meeste ontwikkeltools kunnen die inlezen.

Het aantal aanroepen is per sleutel en per account beperkt (standaard 60 per minuut en 10.000 per dag); bij overschrijding antwoordt de server met 429, wacht dan even. Aanmelden op de website (cookie) opent de API niet, en een sleutel meldt je niet aan bij de webinterface.