Authenticatie | LocatieAPI

De header

Elke aanroep draagt je sleutel in de header X-Api-Key. Er is geen andere methode: geen OAuth, geen bearer-token dat verloopt en geen sleutel in de querystring. Dat laatste is bewust, want querystrings belanden in serverlogs, in browsergeschiedenis en in Referer-headers.

De header

X-Api-Key: lat_test_demo_publiek_locatieapi_sandbox

curl -sS \
  -H "X-Api-Key: lat_test_demo_publiek_locatieapi_sandbox" \
  -H "Accept: application/json" \
  "https://api.locatieapi.nl/v3/lookup/1021JT/19"

$curl = curl_init('https://api.locatieapi.nl/v3/lookup/1021JT/19');
curl_setopt_array($curl, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 5,
    CURLOPT_HTTPHEADER => ['X-Api-Key: lat_test_demo_publiek_locatieapi_sandbox', 'Accept: application/json'],
]);

$body = curl_exec($curl);
$status = curl_getinfo($curl, CURLINFO_RESPONSE_CODE);
curl_close($curl);

$result = $status === 200 ? json_decode($body, true) : null;

use Illuminate\Support\Facades\Http;

$response = Http::withHeaders(['X-Api-Key' => config('services.locatieapi.key')])
    ->acceptJson()
    ->timeout(5)
    ->get('https://api.locatieapi.nl/v3/lookup/1021JT/19');

$result = $response->successful() ? $response->json() : null;

const response = await fetch('https://api.locatieapi.nl/v3/lookup/1021JT/19', {
  headers: {
    'X-Api-Key': 'lat_test_demo_publiek_locatieapi_sandbox',
    Accept: 'application/json',
  },
});

const result = response.ok ? await response.json() : null;

import requests

response = requests.get(
    "https://api.locatieapi.nl/v3/lookup/1021JT/19",
    headers={"X-Api-Key": "lat_test_demo_publiek_locatieapi_sandbox", "Accept": "application/json"},
    timeout=5,
)

result = response.json() if response.ok else None

Live en sandbox

Je account heeft twee soorten sleutels. Ze dragen hun omgeving in de prefix, zodat een sandboxsleutel in productiecode meteen opvalt.

Prefix	Basis-URL	Telt mee voor de bundel	Data
lat_live_	https://api.locatieapi.nl	ja	Alle Nederlandse adressen, dagelijks bijgewerkt
lat_test_	https://sandbox.locatieapi.nl	nee, altijd gratis	Een vaste set testadressen en foutgevallen

Werkt je basis-URL niet vanwege DNS of een firewall, dan kun je terugvallen op https://locatieapi.nl/api. Alle paden werken daar precies hetzelfde.

Toegestane origins

Wil je de API rechtstreeks vanuit de browser aanroepen, bijvoorbeeld voor autocomplete in je checkout, zet dan op de sleutel de domeinen waar hij vandaan mag komen. Zolang een sleutel geen toegestane origins heeft, werkt hij bewust alleen server-side: de API stuurt dan geen Access-Control-Allow-Origin mee en de browser blokkeert het antwoord.

Toegestane origins op een sleutel

https://jouwwinkel.nl
https://www.jouwwinkel.nl
https://staging.jouwwinkel.nl

Gebruik hier een aparte sleutel voor

Een sleutel in frontend-code is voor iedereen zichtbaar. Maak daarom een tweede sleutel met alleen leesrechten, zet daar je origins op en houd je gewone livesleutel op de server. Raakt de frontend-sleutel in verkeerde handen, dan kan hij alleen vanaf jouw domeinen gebruikt worden en trek je hem in één klik in.

Toegestane IP-adressen

Voor server-side sleutels kun je in plaats van origins een lijst met IP-adressen of CIDR-blokken instellen. Aanroepen vanaf een ander adres krijgen een 401. Bruikbaar als je verkeer altijd via één vaste server of uitgaande proxy loopt.

Sleutels intrekken

Een sleutel intrekken werkt direct: de sleutel wordt niet verwijderd maar gemarkeerd, zodat je in je verbruiksoverzicht kunt blijven zien wat hij heeft gedaan. Maak eerst de nieuwe sleutel aan, rol die uit en trek daarna pas de oude in, dan heb je geen onderbreking.

Hoeveel sleutels je tegelijk actief kunt hebben hangt af van je plan; dat staat op de prijzenpagina.

Wat er misgaat

401 application/problem+json

{
  "title": "Invalid API key"
}

Een 401 heeft altijd een van deze oorzaken: de header ontbreekt, de sleutel bestaat niet, de sleutel is ingetrokken, je gebruikt een sandboxsleutel op de live-URL of andersom, of het verzoek komt van een origin of IP-adres dat niet op de sleutel staat. Het X-Request-Id uit de response helpt ons om precies te zien welke van die vijf het was.