API

Utvidelse: Applikasjonsnøkkel og klientnøkkel

Når en aktør har utviklet og testet i testmiljøet vårt og er klar for å gå live med sin integrasjonsløsning, tar de kontakt med API teamet i PowerOffice for å få tilgang.

Rent teknisk vil API teamet opprette en ny utvidelse i Go (en ny applikasjon), og definerer hvilken type applikasjon utvidelsen skal være. Basert på informasjon fra aktøren gir vi utvidelsen et navn, og vi setter rettigheter til de API tjenestene som utvidelsen trenger for å fungere som tiltenkt. Utvidelsen vi oppretter vil ha sin egen unike nøkkel som kalles for en applikasjonsnøkkel. Denne nøkkelen er fast, og knyttet til applikasjonen og eieren av integrasjonen. Nøkkelen kan anses som et brukernavn.

Når utvidelsen aktiveres på en Go klient, vil det genereres en unik klientnøkkel. Denne er helt unik for hver aktiverte integrasjon, så dersom den samme utvidelsen ,"Prima Eksempelsystem", aktiveres på to ulike Go klienter, vil utvidelsen ha hver sin helt unike klientnøkkel på den enkelte klient. Klientnøkkelen er å anse som passordet som integrasjonsparten må bruke, når de skal kommunisere via API mot den enkelte klient.

Med andre ord: Når en utvidelse aktiveres i Go, legger man i praksis til en bruker i Go, og denne brukeren er integrasjonspartens system. For at denne "brukeren" skal kunne kommunisere mot klienten via API, trenger den også et "passord" for å gjøre det, da i form av klientnøkkelen. Det er derfor viktig at klientnøkkelen behandles som et passord - en hemmelighet.

En teknisk beskrivelse av autentiseringen finnes her.

Maskering av nøkler

Fordi klientnøkkelen er å anse som nettopp en hemmelighet, blir den maskert i Go etter at en utvidelse er lagt til - og den vil aldri kunne hentes fram igjen i Go eller av PowerOffice support. Det er derfor viktig at klientnøkkelen kopieres ut og håndteres forsvarlig, første gang man aktiverer en utvidelse og har utvidelsedialogen åpen i Go. Skulle dette bli avglemt eller klientnøkkelen mistet, kan utvidelsen fjernes og aktiveres på nytt. Da blir det generert en ny klientnøkkel (som må formidles til integrasjonsparten og erstatte den gamle).

Illustrasjon av kommunikasjon mot Go: Bruker vs integrasjon

Nedenfor er en enkel skisse som illustrerer API kommunikasjonen mot Go sammenlignet med hvordan en vanlig bruker kommuniserer med Go.