Authenticatie
Authenticatie voor de OptimoCMS API — API keys aanmaken, scopes configureren, sandbox keys gebruiken, rate limits begrijpen en security best practices.
Authenticatie
Alle API requests vereisen authenticatie via een API key in de X-Api-Key header.
API key aanmaken
- Ga naar Instellingen → API Keys in je OptimoCMS dashboard
- Klik op API Key Aanmaken
- Geef de key een beschrijvende naam (bijv. "Productie Backend", "CI/CD Pipeline")
- Selecteer de gewenste scopes
- Kopieer de key — deze wordt slechts één keer getoond
API key gebruiken
REST API
curl https://api.optimocms.com/v1/sites \
-H "X-Api-Key: optimo_live_abc123def456"TypeScript SDK
import { OptimoCMS } from '@optimocms/sdk';
const cms = new OptimoCMS({
apiKey: process.env.OPTIMOCMS_API_KEY!,
});MCP configuratie
{
"mcpServers": {
"optimocms": {
"command": "npx",
"args": ["-y", "@optimocms/mcp-server"],
"env": {
"OPTIMOCMS_API_KEY": "optimo_live_abc123def456"
}
}
}
}Scopes
Scopes bepalen wat een API key mag doen. Gebruik altijd het minimum aan scopes dat je nodig hebt.
| Scope | Beschrijving |
|---|---|
sites:read | Sites ophalen |
sites:write | Sites aanmaken en bijwerken |
pages:read | Pagina's ophalen |
pages:write | Pagina's aanmaken, bijwerken en verwijderen |
media:read | Media bestanden ophalen |
media:write | Media uploaden en verwijderen |
analytics:read | Analytics data ophalen |
ai:write | AI generatie, vertaling en content assist |
publish:write | Sites publiceren |
ecommerce:read | Producten, bestellingen en coupons lezen |
ecommerce:write | Producten en coupons beheren |
booking:read | Boekingen en beschikbaarheid ophalen |
booking:write | Boekingen aanmaken en beheren |
loyalty:read | Loyaliteitspunten ophalen |
loyalty:write | Punten verdienen en inwisselen |
webhooks:read | Webhook configuratie ophalen |
webhooks:write | Webhooks aanmaken en beheren |
forms:read | Formulier inzendingen ophalen |
push:write | Push notificatie campagnes versturen |
Voorbeeld: een key voor alleen content lezen:
Scopes: sites:read, pages:read, media:readVoorbeeld: een key voor een CI/CD pipeline die deployt:
Scopes: sites:read, pages:write, media:write, publish:writeSandbox vs. Live keys
| Sandbox | Live | |
|---|---|---|
| Prefix | optimo_sandbox_ | optimo_live_ |
| Data | Test-data, geen echte publicaties | Productie-data |
| Rate limits | Zelfde als je tier | Zelfde als je tier |
| Kosten | Gratis (AI calls tellen niet mee) | Normaal |
| Publiceren | Geen effect (dry-run) | Site wordt echt gepubliceerd |
Gebruik sandbox keys voor ontwikkeling en testen. Schakel over naar live keys voor productie.
const cms = new OptimoCMS({
apiKey: process.env.NODE_ENV === 'production'
? process.env.OPTIMOCMS_LIVE_KEY!
: process.env.OPTIMOCMS_SANDBOX_KEY!,
});Rate limits
Rate limits zijn afhankelijk van je tier:
| Tier | Requests/min | Burst (per seconde) | Dagelijks maximum |
|---|---|---|---|
| Gratis | 60 | 10 | 5.000 |
| Pro | 600 | 50 | 100.000 |
| Enterprise | 6.000 | 200 | Onbeperkt |
Rate limit headers
Elk API antwoord bevat rate limit informatie:
HTTP/1.1 200 OK
X-RateLimit-Limit: 600
X-RateLimit-Remaining: 594
X-RateLimit-Reset: 1748260860| Header | Beschrijving |
|---|---|
X-RateLimit-Limit | Maximum requests in het huidige window |
X-RateLimit-Remaining | Resterende requests |
X-RateLimit-Reset | Unix timestamp wanneer het window reset |
429 Too Many Requests
Bij overschrijding ontvang je een 429 response:
{
"error": {
"code": "RATE_LIMIT_EXCEEDED",
"message": "Rate limit exceeded. Try again in 45 seconds.",
"details": { "retryAfter": 45 }
},
"meta": { "requestId": "req_abc123", "timestamp": "2026-05-26T12:00:00Z" }
}SDK: De SDK heeft ingebouwde retry met exponential backoff. Zie SDK foutafhandeling.
curl:
# Retry-After header bevat de wachttijd in seconden
curl -i https://api.optimocms.com/v1/sites \
-H "X-Api-Key: jouw_api_key"
# → Retry-After: 45MCP: De MCP server handelt rate limits automatisch af met retry.
Security best practices
1. Gebruik environment variables
# .env (NOOIT committen naar git)
OPTIMOCMS_API_KEY=optimo_live_abc123def456// ✅ Goed
const cms = new OptimoCMS({ apiKey: process.env.OPTIMOCMS_API_KEY! });
// ❌ Fout — hardcoded key
const cms = new OptimoCMS({ apiKey: 'optimo_live_abc123def456' });2. Minimale scopes
Geef elke key alleen de scopes die nodig zijn. Een frontend-integratie heeft geen publish:write nodig.
3. Aparte keys per omgeving
Maak aparte keys voor development, staging en productie. Zo kun je individuele keys revoeken zonder alles te breken.
4. Roteer keys periodiek
Roteer je API keys elk kwartaal. Oude keys kun je revoeken in het dashboard.
5. Monitor gebruik
Houd het API gebruik in de gaten via Instellingen → API Keys → Gebruik. Stel alerts in voor onverwacht hoog gebruik.
6. Nooit client-side
Gebruik API keys nooit in client-side code (browser, mobile app). Maak een backend proxy die de calls doet.
Foutcodes
| Status | Code | Beschrijving |
|---|---|---|
401 | UNAUTHORIZED | Geen of ongeldige API key |
403 | FORBIDDEN | Key heeft niet de juiste scope |
429 | RATE_LIMIT_EXCEEDED | Te veel requests |
{
"error": {
"code": "FORBIDDEN",
"message": "API key does not have scope: pages:write"
},
"meta": { "requestId": "req_err123", "timestamp": "2026-05-26T12:00:00Z" }
}Volgende stappen
- Quickstart — Je eerste API call
- SDK foutafhandeling — Automatische retry bij 429
- API Referentie — Alle endpoints