TOC(heading=API-documentatie)? TOC(heading=HOWTO, sectionindex, compact, depth=3, allactive, Documentatie/Beheerder/HowTos/)? TOC(heading=Beheerder, sectionindex, compact, depth=2, allactive, indirect=Documentatie/Beheerder/TOC)? TOC(heading=Documentatie, sectionindex, compact, depth=1, allactive, Documentatie/)?

API-documentatie

OpenAC 3 is volledig API-gebaseerd. Dat betekent dat de gebruikersinterface gebruikt maakt van API's die ook door externe applicaties kan worden geconsumeerd die aan OpenAC willen koppelen. OpenAC maakt gebruik van technologie waarmee API-documentatie automatisch wordt gegenereerd. Deze documentatie is daarom altijd up-to-date voor de versie die u gebruikt. De documentatie is te vinden via menu Beheer -> API-documentatie. Veel API-endpoints kunnen via deze pagina ook gelijk worden getest.

Authenticatie

Voor de meeste API-endpoints is authenticatie vereist. Authenticeren kan op twee manieren:

• Token based;
• Cookie based;

Token based (JWT-token)

Bij token based authenticatie genereert de OpenAC beheerder een JWT-token en verstrekt deze aan de partij die de OpenAC-API wil gebruiken. Het token heeft een geldigheidsduur. Zolang het token geldig is kan het worden gebruikt om toegang te krijgen tot de OpenAC-API. Omdat het token niet tussentijds kan worden ingetrokken is het belangrijk om de ACL goed in te richten voor het gebruik van de API.

Aanbevelingen ACL-inrichting

Cookie based (Login-API)

Met de login-API kan een sessie worden opgebouwd met de OpenAC 3 server. De API kan zowel met als zonder Two Factor Authentication gebruikt worden. De returnwaarde van de API is gelijk aan het model dat als payload moet worden meegegeven met de POST. Bij Two Factor Authentication moet het teruggekregen model opnieuw worden meegegeven met een tweede aanroep van de API, aangevuld met het beveiligingstoken.

Zonder Two Factor Authentication

“success” en “complete” zijn beide true bij een succesvolle login. “success” en “complete” zijn beide false bij een niet-succesvolle login.

Met Two Factor Authentication

Het inloggen gebeurt in twee fasen, de API moet twee keer worden aangeroepen, de tweede aanroep bevat het bevat het beveiligingstoken. “success” is true bij een succesvolle login. “success” is false bij een niet-succesvolle login.

Als “fase” 2 is dan bevat “message” een bericht aan de gebruiker met informatie over de manier waarop het beveiligingstoken is verstuurd. Hierna moet opnieuw de login API worden aangeroepen met het eerder teruggekregen login-model en “challenge” gevuld met het door de gebruiker ingevulde beveiligingstoken. Als “complete” true is dan is het inlogproces voltooid.

NoteBox(tip,OpenAC geeft bij een succesvolle login een cookie terug die bij alle volgende API-aanroepen moet worden meegegeven.)?

Voorbeeld gebruik

            POST /api/login
           {
              "username": "mkaleb",
              "password": "Ackn0wledge!",
              "agbLocatie": "19009338",
              "agendaLocatie": "h",
              "challenge": "",
              "fase": 0,
              "session": "",
              "success": false,
              "message": "",
              "complete": false
            }