Hoe werkt de beveiliging van de API?

Voor de webservice gelden verschillende beveiligingsniveaus. Er zijn publieke gegevens verzamelingen en methodes en er zijn beveiligde verzamelingen en methodes. Dit wordt in de verschillende pagina's in de handleidingen aangegeven. Bij beveiligde methodes, dient er ingelogd te zijn en dient de ingelogde cliënt de benodigde rechten te hebben.

De verschillende niveaus toegelicht:

• Anoniem gebruik - de methodes die publiek zijn kunnen aangeroepen worden zonder enige vorm van authenticatie. Veelal zijn dit methodes die data gebruiken die in de website ook publiek is. Dit betreft bijvoorbeeld het opvragen van de beschikbare objecten.
  Let op: door het instellen van een API key worden de anonieme calls beveiligd. Nadat de API key is ingesteld dient deze bij alle anonieme opvragingen te worden meegegeven.
• Gebruikersniveau - de gebruiker moet ingelogd zijn en werkt met zijn/haar eigen gegevens. Inloggen gebeurt via de REST interface, zie de user entiteit. Er zijn geen profielen nodig voor een dergelijke gebruiker. Dit is vergelijkbaar met een website waarin een "persoonlijke sectie" is opgenomen. Bijvoorbeeld het tonen van de eigen gegevens of een lijst met boekingen die de gebruiker zelf gemaakt heeft.
• Beheerdersniveau - de gebruiker moet ingelogd zijn en dient een autorisatie profiel te hebben. Afhankelijk van de rechten die beschikbaar zijn in dit profiel, heeft de gebruiker de mogelijkheid data op te vragen en/of te manipuleren. Een complete beheerders applicatie zou kunnen worden gebouwd op deze manier.

Methodes van authenticatie

De gebruikersniveaus - hoger dan anoniem gebruik - zijn op verschillende manieren te bereiken.

• Inloggen via de API
  De API zelf kan gebruikt worden om een sessie aan te maken.
  Dit gebeurt via de API - User.
  Gebruik hiervoor de methode POST user/login. Let op voor het gebruik van het attribuut admin. Zet deze op true voor een beheerders login.
• Basic Auth
  Een methode die veel gebruikt is bij REST api's.
  Zie voor algemene informatie: Open API
  Gebruik de gebruikersnaam + wachtwoord waarmee ook ingelogd wordt in het beheerpaneel.
• Oauth 2
  Zie voor algemene informatie: Open API
  Detail stappen staan hier beschreven.
• API-sleutel (per gebruiker)
  Beschikbaar vanaf i-Reserve versie 5.42.
  Een API-sleutel die aan een specifieke gebruiker gekoppeld is, authenticeert de aanroep alsof die gebruiker is ingelogd. De rechten van die gebruiker (het autorisatieprofiel) bepalen wat de aanroep mag doen — vergelijkbaar met het beheerdersniveau hierboven. Dit is de eenvoudigste methode voor server-naar-server integraties: er is geen aparte login-call nodig en er wordt geen wachtwoord meegestuurd.
  De sleutel wordt per aanroep meegegeven in een header, bijvoorbeeld X-API-KEY: sk_… of Authorization: Bearer sk_….
  Het aanmaken en beheren van deze sleutels staat beschreven in Hoe werkt een API sleutel?

Authenticatie vanaf API-versie 2

Alles hierboven beschrijft versie 1 van de webservice. Vanaf versie 2 — de versie die u kiest met een voorvoegsel in de url, api/rest/v2/… — geldt dat elke aanroep een identiteit heeft. Anoniem gebruik en Basic Auth bestaan daar niet meer. Op versie 1 verandert er niets: bestaande integraties blijven ongewijzigd werken.

Er zijn twee manieren om die identiteit mee te geven:

• Een API-sleutel per gebruiker — de gebruikelijke keuze voor een server-naar-server integratie. Meegeven in de header X-APIKEY. Zie Hoe werkt een API sleutel?
• Een toegangstoken — de keuze voor een app. Een medewerker logt in op een toestel en het token dat daaruit komt gaat mee als Authorization: Bearer <token>. Het token draagt de rechten van die medewerker, net zoals een sleutel dat doet.

Een token vraagt u aan met POST user/auth (gebruikersnaam en wachtwoord) en u vernieuwt het met POST user/refresh. Een app die met een koppelcode aan een omgeving wordt verbonden gebruikt POST app/pair-exchange. Deze drie aanroepen hebben zelf geen sleutel of token nodig — ze delen er juist één uit — en zijn daarom strenger begrensd in het aantal pogingen per IP-adres dan de rest van de API.

Met GET user/me?rights=1 vraagt u op wie de aanroeper is en welke rechten die heeft. Dat is de snelste manier om te achterhalen waarom een aanroep een 403 geeft.