17. Integrations-API og API-nøgler

Integrations-API'et gør det muligt for dit eget program, regneark eller script at læse dine projektdata maskinelt: projektlisten, kabel- og materialelisterne, kredsløbstabellen og klemmelisten for tavlerne, mængdeopgørelsen og sammensætningen af plansættet. API'et læser kun: det ændrer aldrig tegningen eller projektet.

Hvem kan få en API-nøgle

API-adgang aktiveres af driftsansvarlig pr. konto. Når din konto har fået adgang, vises kortet API-nøgler på siden Profil; uden adgang er kortet skjult. En konto kan højst have 5 aktive nøgler ad gangen.

En nøgle ser de samme projekter som dig: dine egne og, efter anmodning, dem der er delt med dig. For et delt projekt returneres lister og mængdeopgørelse kun, hvis delingen også tillader eksport.

Oprettelse af en nøgle

1. På kortet API-nøgler på siden Profil skal du klikke på Ny nøgle.
2. Giv nøglen et navn (for eksempel navnet på det program, der skal bruge den).
3. Vælg omfang: Læs projekter giver projektlisten og projektdata, Læs dokumenter giver listerne, mængdeopgørelsen og plansættet. Vælg kun det, programmet virkelig har brug for.
4. Vælg udløb: 30, 90 eller 365 dage. En udløbet nøgle holder op med at virke; opret en ny i stedet.
5. Angiv din nuværende adgangskode (en konto uden adgangskode kræver en frisk login). Ved din første nøgle skal du acceptere vilkårene for brug af API'et.

Efter oprettelsen vises nøglen kun én gang: kopiér den og opbevar den et sikkert sted. Senere viser listen kun dens præfiks (avk_…) med oprettelses- og udløbsdato, seneste brug og antal kald. Vi sender også en e-mailnotifikation om den nye nøgle (uden selve nøglen).

Tilbagekaldelse af en nøgle

Med knappen Tilbagekald ud for en nøgle bliver den straks ubrugelig; det kan ikke fortrydes. Tilbagekald en nøgle, når du ikke længere bruger den, når du nedlægger det program, der brugte den, eller når du har mistanke om, at den er lækket.

Sikkerhedstips

• Behandl nøglen som din adgangskode: enhver, der kender den, kan læse dine projekter inden for dens omfang.
• Opbevar den i et hemmeligt lager (adgangskodemanager, en miljøvariabel på serveren eller en hemmelig CI-variabel) og ikke i kildekoden: læg den aldrig i et git-repositorium, et delt regneark eller en e-mail.
• Brug den ikke i kode, der kører i en browser (webside, browserudvidelse): der kan alle læse den. En nøgle hører hjemme på en server, i et script eller i et skrivebordsprogram.
• Giv hvert program sin egen nøgle med så snævert et omfang og så kort et udløb som muligt, så tilbagekaldelse af én nøgle ikke stopper noget andet.

Brug fra et program

Nøglen sendes i anmodningens header som et Bearer-token: Authorization: Bearer avk_…. Endepunkterne ligger under /api/v1/ (for eksempel GET /api/v1/projects) og svarer i JSON. Den fulde beskrivelse i OpenAPI-format findes på /api/v1/openapi.json; de fleste udviklerværktøjer kan importere den.

Antallet af kald er begrænset pr. nøgle og pr. konto (som standard 60 pr. minut og 10.000 pr. dag); ved overskridelse svarer serveren med 429, så vent lidt. Login på websitet (cookie) åbner ikke API'et, og en nøgle logger dig ikke ind i webgrænsefladen.