Sådan kommer du igang

Denne vejledning beskriver kort, hvordan man får oprettet en bruger med API adgang og anvender denne til at trække data ud af KITOS.

1 Aktivér API adgang
- 1.1 Rettigheder for API brugeren
2 Swagger dokumentation
3 Anvend bruger til at tilgå APIet
- 3.1 Eksempler
  - 3.1.1 Hent JWT
    - 3.1.1.1 Request
    - 3.1.1.2 Response
  - 3.1.2 Hent data med JWT
    - 3.1.2.1 Request
4 Test API integrationer i staging miljøet

Aktivér API adgang

Lokal Administrator for din organisation skal oprette den bruger, som skal anvendes og KITOS sekretariatet kontaktes for at få aktiveret API adgangen.

Rettigheder for API brugeren

Når brugeren er markeret som API bruger kan

Brugeren bruges til udstedelse af en KITOS Token
Ikke logge på UI (efter release af 11.1.0)
Læse/skrive i henhold til de rettigheder brugeren har fået tildelt i KITOS

Har brugeren ikke fået tildelt en administrativ rolle eller en forretningsrolle (f.eks. systemrolle med skriveadgang), så vil brugeren altså kun have læseadgang til organisationens data.

BEMÆRK: Det anbefales at den oprettede bruger ikke er en “person” i organisationen men en email oprettet til brug for KITOS API integration (f.eks. en gruppe e-mail). Herved hænger adgangen ikke på enkeltpersoner.

Det er dog vigtigt at der kan modtages emails på adressen, da dette benyttes til oprettelse/ændring af passwords for API brugeren.

Swagger dokumentation

Den interaktive swagger dokumentation findes her: Swagger dokumentation

Anvend bruger til at tilgå APIet

Eksempler

Følgende eksempler består af rå HTTP kald og beskriver kort protokollen for at hente JWT og efterfølgende anvende denne til at hente data fra KITOS API.

Hent JWT

Request

POST https://kitos.dk/api/authorize/gettoken/ HTTP/1.1
User-Agent: Fiddler
Host: kitos.dk
Content-Type: application/json
Content-Length: 56

{"email":"EMAIL_INDSÆTTES_HER","password":"PASSWORD_INDSÆTTES_HER"}

Response

HTTP/1.1 200 OK
Cache-Control: no-cache
Pragma: no-cache
Content-Type: application/json; charset=utf-8
Expires: -1
Server: Microsoft-IIS/8.5
X-AspNet-Version: 4.0.30319
X-Powered-By: ASP.NET
Date: Thu, 05 Sep 2019 11:23:29 GMT
Content-Length: 372

{"msg":"","response":{"token":"TOKEN_STÅR_HER","email":"EMAIL_STÅR_HER","loginSuccessful":true,"expires":"UDLØBS_TIMESTAMP_STÅR_HER"}}

Vær opmærksom på at cache JWT, så den kan genbruges inden udløb som er 24 timer efter udstedelse.

Denne information står både i responsbeskeden samt i selve JWT (exp claim). For at afkode JWT til manuelt gennemsyn, kan man anvende https://jwt.io.

Hent data med JWT

For at trække data ud via APIet, autentificeres requestet ved at anvende Bearer token authentication via Authorization headeren.

Eksempel på header:

Authorization: Bearer {TOKEN}

{TOKEN} erstattes af KITOS JWT.

Request

Følgende request henter alle IT-Systemer som brugeren har rettigheder til at se (de første 100)

GET https://kitos.dk/api/v2/it-systems HTTP/1.1
User-Agent: Fiddler
Host: kitos.dk
Authorization: Bearer INDSÆT_TOKEN_HER

For yderligere API endpoints se projektets Swagger dokumentation

Test API integrationer i staging miljøet

Til test og udvikling af API integrationer mod KITOS, anbefales det at starte med at benytte sig af KITOS' staging miljø. Herved er det muligt at teste mod KITOS API uden at en evt. fejl vil påvirke produktionsdata.

Processen for at få API adgang er den samme som i produktionsmiljøet dvs. det er stadig sekretariatet, der skal tillade API adgang på den integrationsbruger, som oprettes af Lokal Admin.