REST API: authenticatie

Elk verzoek aan de REST API van Personyze moet worden geauthenticeerd met een API-sleutel, verstuurd via HTTPS. Er zijn geen openbare endpoints zonder authenticatie.

Heb je het nog niet gelezen, begin dan met REST API: overzicht & snel aan de slag voor de vorm van elk verzoek op hoofdlijnen.

Waar je je API-sleutel vindt

Ga in de beheerinterface van Personyze naar Instellingen → Integraties → API. Elk Personyze-account waartoe je toegang hebt, heeft een eigen sleutel — die zijn niet uitwisselbaar.

Zo stuur je de sleutel mee

Gebruik HTTP Basic Authentication met gebruikersnaam api en de sleutel als wachtwoord. Twee gebruikelijke manieren om dat te doen:

Curl-snelkoppeling — inloggegevens in de URL

Handig om snel iets te testen en voor shellscripts:

curl 'https://api:YOUR_API_KEY@app.personyze.com/rest/users/where/internal_id=42'

Authorization-header — de voorkeur voor productiecode

De meeste HTTP-clientbibliotheken verwerken user:pass@host uit URL’s niet betrouwbaar, en inloggegevens in de URL lekken uit naar de logbestanden van webservers en de browsergeschiedenis. Bouw voor productiecode de Authorization -header expliciet op:

Authorization: Basic <base64("api:" + API_KEY)>

Curl met expliciete header

curl https://app.personyze.com/rest/users/where/internal_id=42 \
     -H "Authorization: Basic $(printf 'api:%s' YOUR_API_KEY | base64)"

Python (requests)

import requests

r = requests.get(
    'https://app.personyze.com/rest/users/where/internal_id=42',
    auth=('api', YOUR_API_KEY),
)
r.raise_for_status()
data = r.json()

JavaScript (fetch)

const r = await fetch(
    'https://app.personyze.com/rest/users/where/internal_id=42',
    { headers: { Authorization: 'Basic ' + btoa('api:' + API_KEY) } }
);
const data = await r.json();

Foutcodes bij authenticatie

Toegang tot meerdere accounts / tenants

De API-sleutel bepaalt op welk Personyze-account het verzoek werkt. De URL van het endpoint noemt het account nooit — dat wordt afgeleid uit de sleutel. Om vanuit dezelfde client met meerdere accounts te werken, houd je één sleutel per account bij en kies je vóór elk verzoek de juiste.

Object-ID’s gelden ook per account: actie 42 in account A heeft niets te maken met actie 42 in account B. Slaat je code Personyze-ID’s op naast je eigen data, sla dan ook de account-ID op (of op zijn minst welke API-sleutel ze heeft aangemaakt), zodat je later verzoeken tegen het juiste account kunt doen.

Snelheidslimieten & time-outs

• Snelle verzoeken van tracker / SDK krijgen een budget van 10 seconden uitvoertijd. Langere verzoeken worden geforceerd verbroken met een fout die voor 503 in aanmerking komt. De meeste aanroepen van de REST API vallen niet onder dit snelle pad, maar houd er rekening mee dat complexe query’s op grote tabellen zorgvuldige indexering nodig kunnen hebben om onder de limiet te blijven.
• POST /rest/users wordt per account beperkt: hooguit één lopende insert tegelijk. Na een wachttijd van 1 seconde in de rij worden verzoeken geweigerd met 400 Too many simultaneous requests. Probeer opnieuw met exponentiële backoff. (Dit staat verder beschreven op de pagina over het object users.)
• Andere endpoints hebben op dit moment geen snelheidslimiet op applicatieniveau — maar behandel de API als een gedeelde bron en bestook hem niet vanuit veel parallelle processen als opeenvolgende aanroepen ook volstaan.

Volgende stappen