GeoRex API authenticatie en best practices

Leer hoe je veilig authenticeert met de GeoRex API, je API keys beheert, en best practices implementeert voor productie-omgevingen.

Een veilige API-implementatie begint bij correcte authenticatie. In dit artikel behandelen we hoe je de GeoRex API veilig gebruikt, je API keys beheert, en welke best practices je moet volgen voor productie-omgevingen.

Authenticatiemethoden

GeoRex gebruikt een twee-stappen token-based authenticatie systeem dat veiligheid combineert met gebruiksgemak:

Security authenticatie flow diagram met server, token service en client applicatie — De twee-stappen token-based authenticatie flow

Stap 1: Token aanvragen

Vraag eerst een tijdelijk token aan met je API key. Dit token is 10 minuten geldig:

Bash

# Token aanvragen met je API key
curl -X POST -H "X-API-Key: gx_live_your_key" \
  "https://api.georex.nl/api/token"

# Response:
# {"token": "grx_abc123...", "expires_in": 600}

Stap 2: Token gebruiken

Gebruik het token vervolgens in alle API requests als query parameter:

Bash

# Geocoding met token
curl "https://api.georex.nl/geocode?q=Damrak+1+Amsterdam&token=YOUR_TOKEN"

# Autocomplete met token
curl "https://api.georex.nl/autocomplete?q=damrak&token=YOUR_TOKEN"

# Reverse geocoding met token
curl "https://api.georex.nl/reverse?lat=52.37&lon=4.89&token=YOUR_TOKEN"

Waarom tokens?

Door tokens te gebruiken in plaats van directe API key authenticatie, voorkom je dat je geheime API key in client-side code terechtkomt. De token kan veilig naar de browser worden gestuurd, terwijl je API key op de server blijft.

API Key Types

GeoRex biedt twee soorten API keys voor verschillende omgevingen:

Type	Prefix	Gebruik	Rate Limits
Test	gx_test_	Ontwikkeling en testen	Lager, gratis
Live	gx_live_	Productie	Volgens je plan

Test keys gebruiken

Gebruik altijd test keys tijdens ontwikkeling. Ze zijn gratis en voorkomen dat je per ongeluk je productie-quota verbruikt.

API Keys veilig opslaan

Environment Variables

Sla API keys altijd op als environment variables, nooit hardcoded in je code:

.env

Bash

# .env bestand (NOOIT committen naar git!)
GEOREX_API_KEY=gx_live_xxxxxxxxxx

config.js

JavaScript

// Goed: environment variable
const apiKey = process.env.GEOREX_API_KEY;

// FOUT: hardcoded key
const apiKey = "gx_live_xxxxxxxxxx"; // ❌ Doe dit NOOIT

Git Ignore

Zorg ervoor dat je .env bestanden altijd in je .gitignore hebt staan:

.gitignore

Bash

# Environment files
.env
.env.local
.env.*.local

# API keys
*.key
secrets/

Rate Limiting

De GeoRex API heeft rate limits om misbruik te voorkomen. De actuele limits worden meegestuurd in de response headers:

Bash

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 998
X-RateLimit-Reset: 1704067200

Rate limiting implementeren

Visualisatie van rate limiting met requests over tijd — Rate limiting beschermt de API en zorgt voor eerlijke verdeling van resources

rate-limit-handler.js

JavaScript

class GeoRexClient {
  constructor(apiKey) {
    this.apiKey = apiKey;
    this.token = null;
    this.tokenExpiry = 0;
    this.rateLimitRemaining = Infinity;
    this.rateLimitReset = null;
  }

  async getToken() {
    // Vernieuw token als bijna verlopen (binnen 1 minuut)
    if (!this.token || Date.now() > this.tokenExpiry - 60000) {
      const res = await fetch('https://api.georex.nl/api/token', {
        method: 'POST',
        headers: { 'X-API-Key': this.apiKey }
      });
      const data = await res.json();
      this.token = data.token;
      this.tokenExpiry = Date.now() + (data.expires_in * 1000);
    }
    return this.token;
  }

  async geocode(address) {
    // Check rate limit
    if (this.rateLimitRemaining <= 0 && this.rateLimitReset) {
      const waitTime = this.rateLimitReset - Date.now();
      if (waitTime > 0) {
        console.log(`Rate limit bereikt, wacht ${waitTime}ms`);
        await this.sleep(waitTime);
      }
    }

    const token = await this.getToken();
    const query = encodeURIComponent(address);
    const response = await fetch(
      `https://api.georex.nl/geocode?q=${query}&token=${token}`
    );

    // Update rate limit info
    this.rateLimitRemaining = parseInt(
      response.headers.get('X-RateLimit-Remaining') || Infinity
    );
    this.rateLimitReset = parseInt(
      response.headers.get('X-RateLimit-Reset') || 0
    ) * 1000;

    if (response.status === 429) {
      const data = await response.json();
      await this.sleep((data.retry_after || 60) * 1000);
      return this.geocode(address);
    }

    return response.json();
  }

  sleep(ms) {
    return new Promise(resolve => setTimeout(resolve, ms));
  }
}

Error Handling

Implementeer robuuste error handling voor alle mogelijke foutscenario's:

error-handler.js

JavaScript

async function geocodeWithErrorHandling(address, token) {
  try {
    const query = encodeURIComponent(address);
    const response = await fetch(
      `https://api.georex.nl/geocode?q=${query}&token=${token}`
    );

    switch (response.status) {
      case 200:
        return await response.json();

      case 400:
        throw new Error('Ongeldig adresformaat');

      case 401:
        throw new Error('Token verlopen of ongeldig');

      case 404:
        return { features: [] }; // Adres niet gevonden

      case 429:
        const data = await response.json();
        throw new Error(`Rate limit bereikt. Wacht ${data.retry_after}s`);

      case 500:
        throw new Error('Server error, probeer later opnieuw');

      default:
        throw new Error(`Onverwachte status: ${response.status}`);
    }
  } catch (error) {
    if (error.name === 'TypeError') {
      throw new Error('Netwerkfout, controleer je verbinding');
    }
    throw error;
  }
}

Security Checklist

Gebruik deze checklist voor je productie-deployment:

✅ API keys opgeslagen als environment variables
✅ .env bestanden toegevoegd aan .gitignore
✅ Gescheiden test en live keys voor verschillende omgevingen
✅ Rate limiting geïmplementeerd in je client
✅ Error handling voor alle HTTP statuscodes
✅ HTTPS gebruikt (nooit HTTP)
✅ API keys regelmatig geroteerd
✅ Monitoring voor ongewoon API gebruik

Key compromised?

Als je vermoedt dat een API key is gelekt, roteer deze dan onmiddellijk via je GeoRex dashboard. Oude keys worden direct ongeldig.

Volgende stappen

Nu je authenticatie correct hebt ingesteld, kun je verder met:

Batch geocoding voor grote datasets
Webhooks voor real-time notificaties
Privacy-first geocoding voor GDPR-compliance

GeoRex API authenticatie en best practices

Authenticatiemethoden

Stap 1: Token aanvragen

Stap 2: Token gebruiken

API Key Types

API Keys veilig opslaan

Environment Variables

Git Ignore

Rate Limiting

Rate limiting implementeren

Error Handling

Security Checklist

Volgende stappen

Gerelateerde artikelen

Je eerste geocoding API call in 5 minuten

Geocoding vs Reverse Geocoding: Wat is het verschil?

Van adres naar coördinaten: een complete handleiding

Klaar om te beginnen met GeoRex?

Cookie-instellingen