Beveiliging API
De ControlOffice API heeft twee verschillende beveiligingsmechanismen. Deze worden in dit artikel uitgelegd.
Bearer Token
Vrijwel alle endpoints van de API zijn beveiligd met een bearer token, dat wordt meegegeven in de Authorization-header. Dit token kan worden verkregen via het token-endpoint, dat logischerwijs zelf niet op deze wijze is beveiligd:
POST /api/v1/token
De body van het request dient een JSON-object te zijn met de volgende structuur:
{
"username": "<gebruikersnaam>",
"password": "<wachtwoord>"
}
De response is eveneens een JSON-object:
{
"token": "<het access token>",
"expires": "<vervaldatum/tijdstip in UTC>"
}
API Key
Bijna alle GET-endpoints volgen de OData-standaard, waardoor het mogelijk is om te filteren, sorteren, etc. Deze endpoints accepteren een access token, maar het is ook mogelijk om een API key te gebruiken. Dit is bijvoorbeeld handig voor integraties met Power BI.
Een API key is gekoppeld aan een gebruiker en heeft dezelfde rechten als die gebruiker. Je kunt een API key opvragen via de ControlOffice webapplicatie. Log in en klik rechtsboven op je gebruikersnaam. Kies vervolgens in het dropdownmenu voor "OData API Key". Dit menu-item is beveiligd met een gebruikersrecht. Als de optie niet zichtbaar is, controleer dan of de juiste rechten zijn toegekend.
Let op, de API-key is 1 jaar geldig.
De API key wordt meegegeven in de header X-CO-APIKEY van een GET-request. Als alternatief kan de key ook worden doorgegeven als queryparameter met dezelfde naam.