Voor ontwikkelaars

Je app koppelen

De drie manieren waarop je eigen app en 1plek elkaar raken — gegevens ophalen, gebeurtenissen melden, en gebruikers doorlaten.

1plek is de plek waar het werk samenkomt: postvakken, contacten, agenda, personeel, berichten. Je eigen app kent de bedrijfslogica: wat een bestelling is, wanneer een cursus vol zit, wie een klant is.

Die twee raken elkaar op drie plekken, en verder nergens. Dat is met opzet: hoe smaller het raakvlak, hoe minder er kapot kan als een van de twee verandert.

1plek komt nooit in je database. Alles hieronder loopt over HTTP, met een sleutel die jij intrekt wanneer je wilt.

1. Gegevens ophalen (jij vraagt)

Contactgegevens en social links beheer je één keer in 1plek, en je site haalt ze op. Zo staat je telefoonnummer niet in drie codebases.

bash

curl https://iam.1plek.com/api/platform/companies/<bedrijf>/profile \
  -H "Authorization: Bearer $ONEPLEK_API_KEY"

Een sleutel met het recht company:read maak je bij het bedrijf, tabblad Integraties.

De route stuurt een ETag mee en antwoordt met 304 als er niets veranderd is, dus je kunt goedkoop blijven pollen. Cache het antwoord en val terug op je eigen standaard als 1plek even niet bereikbaar is — je site hoort te blijven werken als wij een storing hebben.

Bewust ophalen en geen webhook: dit verandert een paar keer per jaar, en een pull heeft geen retry-machinerie nodig die zelf weer kan falen.

2. Gebeurtenissen melden (jij duwt)

Het spiegelbeeld: jouw app meldt dát er iets gebeurd is, 1plek verstuurt wat je team eraan gekoppeld heeft.

bash

curl -X POST https://iam.1plek.com/api/platform/companies/<bedrijf>/events/order.paid \
  -H "Authorization: Bearer $ONEPLEK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"payload":{"email":"klant@example.com","orderNumber":"1234"}}'

Je hoeft een gebeurtenis niet vooraf aan te melden en je hoeft niets te weten over de berichten eromheen — welk sjabloon, welke huisstijl, welk kanaal, dat kiest het team in 1plek. Volledige uitleg staat bij Gebeurtenissen melden via de API.

Wil je andersom weten wanneer er iets in 1plek gebeurt, gebruik dan webhooks.

3. Gebruikers doorlaten (eenmalig inloggen)

Iemand die in 1plek is ingelogd en jouw app opent, hoort niet opnieuw te hoeven inloggen. Daarvoor geeft 1plek een kortlevend token mee dat jouw app verifieert, waarna jouw app zijn eigen sessie aanmaakt.

Het token:

leeft 60 seconden en is één keer bedoeld;
bevat alleen identiteit — een e-mailadres en een naam. Geen sessie, geen wachtwoord, geen sleutels;
heeft de vorm <base64url(payload)>.<base64url(handtekening)>;
kan een claim dragen dat een teamlid namens een klant kijkt, zodat jouw app dat kan tonen en vastleggen.

Voor het ondertekenen zijn er twee smaken:

Manier	Wat jouw app nodig heeft	Wanneer
Gedeeld geheim (HMAC)	Hetzelfde geheim	Simpel; jouw app kan zelf ook tokens maken
Sleutelpaar (Ed25519)	Alleen de publieke sleutel	Veiliger; jouw app kán geen tokens maken

Kies het sleutelpaar als je de keuze hebt: dan kan een lek aan jouw kant geen geldige tokens produceren.

Verifieer de handtekening én de leeftijd van het token vóór je er een sessie op maakt, en keur het pad of de bestemming aan jouw kant. Vertrouw nooit een veld omdat het in het token stond zonder eerst de handtekening te controleren.

Sleutels en omgevingen

Elke omgeving van je app heeft zijn eigen sleutels: die van je testomgeving horen niet op productie en andersom. Hoe je die omgevingen naast elkaar zet, staat bij Omgevingen en synchroniseren.

Zet elke sleutel in de omgevingsvariabelen van je app, nooit in code die naar de browser gaat.