17. Integrasjons-API og API-nøkler

Integrasjons-API-et gjør at ditt eget program, regneark eller skript kan lese prosjektdataene dine maskinelt: prosjektlisten, kabel- og materiallistene, kursoversikten og klemmelisten for tavlene, mengdeberegningen og sammenstillingen av tegningspakken. API-et er skrivebeskyttet: det endrer verken tegningen eller prosjektet.

Hvem kan få en API-nøkkel

API-nøkkel aktiveres av driveren for hver konto. Hvis kontoen din har fått tilgang, vises kortet API-nøkler på siden Profil; uten tilgang er kortet skjult. En konto kan ha høyst 5 aktive nøkler samtidig.

Nøkkelen ser de samme prosjektene som du: dine egne, og på forespørsel de som er delt med deg. For et delt prosjekt returneres lister og mengdeberegning bare hvis delingen også tillater eksport.

Opprette en nøkkel

På kortet API-nøkler på siden Profil klikker du på knappen Ny nøkkel.
Gi nøkkelen et navn (for eksempel navnet på programmet som skal bruke den).
Velg omfang: Les prosjekter gir prosjektlisten og prosjektdataene, Les dokumenter gir listene, mengdeberegningen og tegningspakken. Velg bare det programmet faktisk trenger.
Velg utløp: 30, 90 eller 365 dager. En utløpt nøkkel slutter å virke; du oppretter en ny i stedet.
Skriv inn ditt nåværende passord (en konto uten passord trenger en fersk innlogging). For den første nøkkelen må du godta vilkårene for bruk av API-et.

Etter opprettelsen vises nøkkelen bare én gang: kopier den og oppbevar den et trygt sted. Senere viser listen bare prefikset (avk_…), med opprettelses- og utløpsdato, siste bruk og antall kall. Vi sender også et varsel på e-post om den nye nøkkelen (uten selve nøkkelen).

Tilbakekalle en nøkkel

Med knappen Tilbakekall ved siden av nøkkelen på kortet blir nøkkelen umiddelbart ubrukelig; dette kan ikke angres. Tilbakekall nøkkelen når du ikke bruker den lenger, når du legger ned programmet som brukte den, eller hvis du mistenker at den er lekket.

Sikkerhetsråd

Behandle nøkkelen som passordet ditt: den som kjenner den, kan lese prosjektene dine innenfor det angitte omfanget.
Oppbevar den i et hemmelighetslager (passordbehandler, miljøvariabel på serveren eller hemmelig variabel i CI), ikke i kildekoden: den må ikke havne i git-repoet, i et delt regneark eller i en e-post.
Ikke bruk den i kode som kjører i nettleseren (nettside, nettleserutvidelse): der kan hvem som helst lese den. Nøkkelen hører hjemme på en server, i et skript eller i et skrivebordsprogram.
Gi hvert program sin egen nøkkel med så snevert omfang som mulig og kort utløp; da stopper ikke tilbakekalling av én nøkkel noe annet.

Bruk fra et program

I forespørselens header sendes nøkkelen som Bearer-token: Authorization: Bearer avk_…. Endepunktene ligger under /api/v1/ (for eksempel GET /api/v1/projects) og svarer i JSON. Den nøyaktige beskrivelsen i OpenAPI-format finnes på /api/v1/openapi.json; de fleste utviklerverktøy kan importere den.

Antall kall er begrenset per nøkkel og per konto (som standard 60 per minutt og 10 000 per døgn); ved overskridelse svarer serveren med 429, så vent litt. Innlogging på nettstedet (informasjonskapsel) åpner ikke API-et, og nøkkelen logger deg ikke inn i nettgrensesnittet.