‹ Overzicht
Freave Services API

Aan de slag met de Freave API

Foutafhandeling

› Authenticatie



Authenticatie

Gepubliceerd op 12-10-2018 | Geüpdatet op 14-10-2018

De Freave Services API kent een aantal vormen voor authenticatie. In de praktijk zult u alleen de AccessKey gebruiken, de andere vormen zijn voor intern gebruik.

AccessKey-authenticatie

Een access key is een unieke sleutel welke bestaat uit een reeks willekeurige letters, cijfers en leestekens. Hij wordt gebruikt om verzoeken aan de API te herleiden naar een organisatie en gebruiker.

Uw access key wordt gelinkt aan de account waarmee u hem maakt. Maakt u een bron aan met een access key? Dan zal de account waarmee de access key is gemaakt als “creator” worden getoond. Het kan daarom in sommige gevallen handig zijn om een “API-gebruiker” te maken. Zo ontstaat er geen verwarring over wie de bron heeft aangemaakt.

  • Access keys zijn gelinkt aan een organisatie en de gebruiker die hem maakt.
  • Access keys verlopen niet uit zichzelf, ze kunnen wel op elk moment worden ingetrokken.
  • Access keys kunnen worden gelinkt aan een IP-adres om te voorkomen dat als een access key uitlekt deze kan worden misbruikt.
  • Het is niet mogelijk om het gelinkte IP-adres nadat deze is aangemaakt aan te passen.

Bescherm een AccessKey zoals u ook uw wachtwoord zou beschermen. Als het uitlekt kan iemand onder uw account kosten maken.

Een access key maken

  1. Log in bij ons klantportaal.
  2. Ga naar “gegevens”, vervolgens “API-toegang”.
  3. Selecteer “nieuwe access key maken”.
    • Geef een referentie op voor uw access key.
    • Geef optioneel een IP-adres op. De access key kan dan alleen vanaf het opgegeven IP-adres worden gebruikt. Zo kunt u misbruik voorkomen.
  4. Selecteer “maken”.
  5. U komt nu in het overzicht terecht en kunt uw access key kopiëren.

Uw access key gebruiken

U moet uw access key in de Authorization-header verzenden als u onze API gebruikt. Dit moet u doen voor alle eindpunten die authenticatie vereisen. Als u de authenticatie-header vergeet zal de API een 401 Authenticatie Vereist-fout teruggeven.

Als de access key ongeldig is zal de API een 403 Toegang verboden-fout teruggeven. Daarnaast zal de API een JSON-foutobject teruggeven met meer informatie over de fout.

Formaat van authenticatie-header
Authorization: AccessKey {uw access key}

Codevoorbeeld in PHP

Onderstaand een codevoorbeeld in PHP. Met het verzoek haalt u uw eigen gegevens op en laat deze zien. Het voorbeeld gebruikt een access key voor authenticatie.

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api.freave.com/v4/me",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_HTTPHEADER => array(
    "Authorization: AccessKey {uw access key}",
    "Content-Type: application/json"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}