OAuth2 flow

👍
Booking Experts highly recommends this method of authentication
Moving forward we will encourage more and more of our new and existing applications to only use OAuth when it comes to authentication.

You can authenticate organizations by using OAuth2. For quick result needs you can make use of an API key, but this has limited access to only the organization and its linked administrations to which it is registered.

If you want others to make use of your app you will need to support OAuth2. The flow for authenticating organizations via OAuth2 is described in the following diagram:

Store your OAuth2 client UID and keep it secret.
These have been supplied after your app was created and can be found on the admin page of the app
When a user installs an app, a dialog will be shown listing all permissions that the app will need.
When accepted, your specified redirect URL will be called with a code in the query string and nothing else.
This follows the standard OAuth2 protocol. You need to use this code to fetch a token and refresh token via the https://api.bookingexperts.nl/oauth/token endpoint by passing the supplied code.
Most OAuth2 clients will use this path by default.
Turn the unique code into a token.
Per organization that successfully installs the app, you will receive a unique code which you need to turn into a token.
After fetching a token, you can now access the API.
The first thing to do is to fetch and persist the details of the subscription for the token you just received via the endpoint https://api.bookingexperts.nl/v3/subscription.
This will yield the current subscription ID, the administration IDs to which you've been granted access and a return URL back to the BookingExperts app page.
You can now render a success response to the user
This could include a message explaining that the app has successfully been installed and an introductory message of how the user should proceed. It can also include a button back to the app page in BookingExperts as returned by the subscription details.

Example

1) User clicks "Install" in App Store
2) User is redirected to callback url hosted by the App. The Authorization Response is send to the App Server. For example:

HTTP/1.1 302 Found
Location: https://your-domain.com/booking_experts/oauth_callback?code=P66tmn20oiwyJRoHsN1iyNOzy37vKpRg8pEapG7s_ps

3) The App can then use the code url parameter to fetch the OAuth tokens. The App sends the Authorization Code Request For example:

POST /oauth/token HTTP/1.1
Host: app.bookingexperts.nl

code=P66tmn20oiwyJRoHsN1iyNOzy37vKpRg8pEapG7s_ps
&grant_type=authorization_code
&redirect_uri=https://your-domain.com/booking_experts/oauth_callback
&client_id=[CLIENT_ID]
&client_secret=[CLIENT_SECRET]

4) Booking Experts server returns the Access Token Response for example:

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
{
  "access_token":"MTQ0NjJkZmQ5OTM2NDE1ZTZjNGZmZjI3",
  "token_type":"Bearer",
  "expires_in":604800,
  "refresh_token":"IwOGYzYTlmM2YxOTQ5MGE3YmNmMDFkNTVk",
  "scope":"create"
}

5) Now you can make API requests to the Booking Experts API for example:

curl --request GET \
  --url https://api.bookingexperts.nl/v3/administrations \
  --header 'accept: application/vnd.api+json' \
  --header 'accept-language: en,nl' \
  --header 'authorization: Bearer [ACCESS_TOKEN]'

6) After a while the access token will expire. In that case you will receive a response from the Booking Experts something like:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer error="invalid_token" error_description="The access token expired"
Content-type: application/json
{
  "error": "invalid_token",
  "error_description": "The access token expired"
}

7) In that case you should request a new acces_token using the refresh_token. The App should send a Refresh token request.

POST /oauth/token HTTP/1.1
Host: app.bookingexperts.nl

grant_type=refresh_token
&refresh_token=[REFRESH_TOKEN]
&client_id=[CLIENT_ID]
&client_secret=[CLIENT_SECRET]

8) The Booking Experts server returns a Token response which should be used for new API requests untill the token expires (see step 6.)

{
 "access_token": "BWjcyMzY3ZDhiNmJkNTY",
 "refresh_token": "Srq2NjM5NzA2OWJjuE7c",
 "token_type": "Bearer",
 "expires": 3600
}

👍Booking Experts highly recommends this method of authentication

👍
Booking Experts highly recommends this method of authentication