De MyOrganizer API gebruikt zoveel mogelijk standaarden op gebied van authenticatie en authorisatie.
Zo maken we gebruiken van OAuth2 en meer bepaald de authorization code grand om te authenticeren.

Voor u start, heeft u steeds van ons een Client ID en Secret nodig. U kan deze aanvragen via support@ringphone.be

Integrators communiceren met onze API steeds in naam van een van onze klanten. Zo zal u dus in uw applicatie iets moeten inbouwen waarmee de klant een eerste keer inlogt met zijn MyOrganizer API account. Nadien kan u via tokens in naam van de klant communiceren met de API. U heeft dan uiteraard enkel toegang tot de agenda en/of groepspraktijk van de klant. Indien de klant op een bepaald moment geen toegang meer heeft tot Myorganizer, zal ook uw applicatie niet meer kunnen communiceren met de API in naam van de klant.

Bij de aanvraag tot toegang is het belangrijk ons mee te sturen welke calls uw applicatie wil uitvoeren op onze API. Het is niet omdat u kan authenticeren dat u automatisch ook toegang heeft tot al onze API’s. Iedere API wordt geassocieerd met scopes en als integrator krijgt uw applicatie enkel toegang tot de API acties die wij voor uw applicatie toelaten. Zo kan het bevoorbeeld goed mogelijk zijn dat u afspraken kan ophalen, maar geen nieuwe afspraken kan aanmaken. Ook moet de klant u toegang verlenen om in zijn naam deze acties te kunnen uitvoeren.

In het kort:

Toegang tot de api gebeurt via 2 security lagen.

  1. Uw applicatie zal altijd communiceren in naam van een van onze klanten. (authenticatie)

  2. Uw applicatie krijgt toegang tot bepaalde API acties via scopes (authorisatie)

De combinatie van bovenstaande zorgt dus uiteindelijk tot welke data u toegang heeft op onze API.

Opgelet: Onderstaande documentatie is eerder technisch en wordt beschouwd voor uw ontwikkelingsteam

JWT (Json web token)

Wie u bent en wat u allemaal mag doen zit uiteindelijk bevat in en Json web token (JWT) of access token. U dient dit token op te vragen bij onze Identity provider en mee te sturen bij iedere call naar onze API.

Uiteraard is deze JWT slechts voor een bepaalde tijd geldig. Om nadien als applicatie opnieuw toegang te krijgen tot onze api hoeft de klant niet meer opnieuw in te loggen. U kan een nieuwe access token ophalen via de refresh token die in de eerste response bevat zat.

Onderstaande flows beschrijven het authenticatie mechanisme op de meest eenvoudige manier

Hieronder een voorbeeld inclusief het refresh token mechanisme zonder dat de klant dus telkens opnieuw moet gaan inloggen

MyOrganizer gebruikt Microsoft Azure als identity provider. Uitgebreide developer documentatie kan u vinden op deze pagina met een eenvoudige illustratie in volgende afbeelding.

Scopes die u kan meesturen bij het ophalen van de tokens:

  • offline_access → zodat u een refresh token kan terug krijgen

  • Application scopes:

Opgelet: het kan zijn dat u geen toegang heeft tot alle application scopes. Vraag dit na via support@ringphone.be

How to:

  1. Ophalen van de authorisatie token:

Authenticatie url:
https://ringphonesso.b2clogin.com/ringphonesso.onmicrosoft.com/B2C_1_MyOrganizer_Login/oauth2/v2.0/authorize

Probeer het zelf via:
GET https://ringphonesso.b2clogin.com/ringphonesso.onmicrosoft.com/B2C_1_MyOrganizer_Login/oauth2/v2.0/authorize?response_type=code&state=&client_id={uwclientId}&scope=offline_access {scopes gescheiden via spatie}&redirect_uri={redirect url naar uw applicatie}

2. Ophalen van de access token:

Access token url:
https://ringphonesso.b2clogin.com/ringphonesso.onmicrosoft.com/B2C_1_MyOrganizer_Login/oauth2/v2.0/token

Probeer het zelf via:
POST
https://ringphonesso.b2clogin.com/ringphonesso.onmicrosoft.com/B2C_1_MyOrganizer_Login/oauth2/v2.0/token
body:
grant_type=authorization_code&code={de ontvangen authorisatie code of refresh token}&redirect_uri={redirect url naar uw applicatie}&client_id={uwclientId}&client_secret={uwclientsecret}

De ontvangen jwt dient bij iedere call naar onze api meegestuurd te worden via the basic authorisation header.

We hebben ook een postman file die onmiddellijk de juiste url’s voor u invult als voorbeeld. Contacteer ons hiervoor via support@ringphone.be