Bouw met Praxium.

API-keys worden bij creatie HMAC-getekend: de sleutel zelf bevat zijn eigen integriteitsbewijs in het formaat praxium_v1_<tenant>_<profile>_<timestamp>_<signature>, waarbij de signature HMAC-SHA256 wordt afgeleid op de server vanuit een per-profiel signing secret dat versleuteld in de database staat — het secret komt nooit op de wire, alleen de signature die het produceert. De tenant-slug is cryptografisch in de signature gebonden, dus een key uitgegeven voor tenant A kan niet worden hergebruikt op tenant B zonder de verificatie te breken. Bij binnenkomst verifieert de server de integriteit van de key end-to-end voordat er data wordt teruggegeven, en vervalste of hergerichte keys worden geweigerd met 403.

Requests authenticeren via de standaard Authorization: Bearer <key> over HTTPS — hetzelfde patroon dat GitHub, OpenAI, Slack en Notion gebruiken.

Daarbovenop is elke sleutel gescoped naar één API-profiel dat precies definieert welke entiteitstypen en velden uitleesbaar zijn. Elke integratie communiceert alleen met de data die strikt nodig is — het principe van least privilege, afgedwongen op veldniveau in plaats van op endpoint-niveau. Intrekken of roteren kan per profiel via de admin-portal.

Stuur Accept-Language: nl, Accept-Language: en of Accept-Language: ro wanneer je site één taal rendert. Tenant-API's gebruiken de gevraagde taal alleen wanneer die voor de tenant is ingeschakeld; anders gebruiken ze de standaardtaal van de tenant.

Elk endpoint houdt één gedocumenteerde response-vorm. Velden die als taalspecifiek zijn gedocumenteerd—zoals FAQ-categorienamen, vragen en antwoorden, en labels en waarden van custom fields voor teamleden—komen terug als strings. Velden die in OpenAPI als locale-maps zijn gedocumenteerd, houden die vaste vorm.

Voor taalspecifieke velden valt een ontbrekende vertaling terug op de beste beschikbare gepubliceerde tekst in plaats van een lege string.

Elke bezorging bevat één header X-Praxium-Signature: t=<unix_ts>,sha256=<hmac_hex>, waarbij de HMAC-SHA256 op de server wordt berekend over ${timestamp}.${rawBody} met het per-webhook secret. Het gedeelde secret komt nooit op de wire — alleen de HMAC-output gaat over de lijn. De signature bewijst twee dingen tegelijk: de body is niet gemanipuleerd onderweg (integriteit), en de aanroep komt daadwerkelijk van Praxium en niet van een aanvaller die jouw endpoint-URL heeft geraden (authenticiteit). Alle bezorgingen gaan over HTTPS — Praxium accepteert geen webhook-URL's zonder HTTPS in deployed-omgevingen.

Als webhook-ontvanger ben je verantwoordelijk voor het verifiëren van elke bezorging — Praxium tekent en bezorgt, maar de handhaving gebeurt in jouw handler. Gebruik je @praxium/sdk, dan hoef je hier niets van met de hand te schrijven: processWebhook() (framework-agnostic) en createRevalidationHandler() (Next.js ISR) bakken alle vier stappen plus replay-protection in. Hand-implementeren in een andere runtime? De vier stappen zijn: (1) parse timestamp en signature uit de header, (2) wijs bezorgingen ouder dan je replay-window af — 5 minuten is de standaard, (3) bereken de HMAC opnieuw over ${timestamp}.${rawBody} met je eigen secret, (4) vergelijk met constant-time comparison (bijv. crypto.timingSafeEqual op Node).

Dit is hetzelfde schema dat Stripe gebruikt voor webhook-signatures. Per-webhook secrets worden precies één keer teruggegeven — in de response bij het aanmaken van de webhook en in de response bij elke rotatie — en verschijnen daarna nergens meer. Dat eenmalige tonen betekent dat het secret aan onze kant geen langdurig aanvalsoppervlak is: zelfs een gecompromitteerde admin-sessie kan het niet meer ophalen. Nieuwe nodig? Roteer vanuit de admin-portal — het nieuwe secret komt in de rotatie-response, het vorige wordt direct ongeldig, en andere subscriptions blijven ongemoeid.