17. Integrations-API och API-nycklar

Integrations-API:et gör att ditt eget program, kalkylblad eller skript kan läsa dina projektdata maskinellt: projektlistan, kabel- och materiallistorna, gruppförteckningen och plintlistan för elcentralerna, mängdavtagningen och sammanställningen av ritningspaketet. API:et är skrivskyddat: det ändrar varken ritningen eller projektet.

Vem kan få en API-nyckel

API-nyckeln aktiveras av driftansvarig för varje konto. Om ditt konto har fått behörighet visas kortet API-nycklar på sidan Profil; utan behörighet syns inte kortet. Ett konto kan ha högst 5 aktiva nycklar samtidigt.

Nyckeln ser samma projekt som du: dina egna och, på begäran, de som har delats med dig. För ett delat projekt lämnas listorna och mängdavtagningen ut endast om delningen också tillåter export.

Skapa en nyckel

På kortet API-nycklar på sidan Profil klickar du på knappen Ny nyckel.
Ge nyckeln ett namn (till exempel namnet på programmet som ska använda den).
Välj behörighetsomfång: Läsa projekt ger projektlistan och projektens data, Läsa dokument ger listorna, mängdavtagningen och ritningspaketet. Ange bara det som programmet verkligen behöver.
Välj giltighetstid: 30, 90 eller 365 dagar. En utgången nyckel fungerar inte längre; du skapar en ny i stället.
Ange ditt nuvarande lösenord (för ett konto utan lösenord krävs en ny inloggning). Vid den första nyckeln godkänner du villkoren för API-användning.

Efter skapandet visas nyckeln bara en enda gång: kopiera den och förvara den på ett säkert ställe. Därefter syns bara dess prefix (avk_…) i listan, med datum för skapande och utgång, senaste användning och antal anrop. Vi skickar också ett e-postmeddelande om den nya nyckeln (utan själva nyckeln).

Återkalla en nyckel

Med knappen Återkalla bredvid nyckeln på kortet blir nyckeln oanvändbar omedelbart; det går inte att ångra. Återkalla nyckeln när du inte längre använder den, när du lägger ned programmet som använde den, eller om du misstänker att den har läckt.

Säkerhetsråd

Behandla nyckeln som ditt lösenord: den som känner till den kan läsa dina projekt inom det angivna omfånget.
Förvara den i ett hemlighetsförvar (lösenordshanterare, serverns miljövariabel eller CI:ns hemliga variabel), inte i källkoden: den får inte hamna i git-arkivet, i ett delat kalkylblad eller i ett e-postmeddelande.
Använd den inte i kod som körs i webbläsaren (webbsida, webbläsartillägg): där kan vem som helst läsa ut den. Nyckelns plats är på en server, i ett skript eller i ett skrivbordsprogram.
Ge varje program en egen nyckel med så snävt omfång och så kort giltighetstid som möjligt; då stoppar återkallandet av en nyckel inget annat.

Användning från ett program

I anropets huvud skickas nyckeln som Bearer-token: Authorization: Bearer avk_…. Slutpunkterna ligger under /api/v1/ (till exempel GET /api/v1/projects) och svaret är JSON. Den exakta beskrivningen i OpenAPI-format finns på /api/v1/openapi.json; de flesta utvecklingsverktyg kan läsa in den.

Antalet anrop är begränsat per nyckel och per konto (som standard 60 per minut och 10 000 per dygn); vid överskridning svarar servern med 429, vänta då en stund. Webbinloggning (kaka) öppnar inte API:et, och en nyckel loggar inte in dig i webbgränssnittet.