Domains

Please note that the domain for accounts related endpoints is not the same as the domain of the api endpoints. It is located on accounts.bakeronline.be instead of api.bakeronline.be. You can read more about domains on the domain documentation page.

Using OAuth 2.0

In order to let your application do things on behalf of one of our users, you need to authenticate and ask approval of one of our users.

When you successfully authenticated, you receive an access_token and a refresh_token. You need to include the access_token in the Authorization HTTP header when you want to do a request on behalf of the user (e.g. request information that is only available for that user).

e.g.

GET /company/shops HTTP/1.1
Authorization: Bearer <your access token>

Set the Authorization header to Bearer eyJ...fdgs (= Bearer+   + access_token) to enable authenticated requests.

The OAuth Flow

Bakeronline uses the OAuth 2.0's authorization code grant flow to issue access tokens on behalf of users. You only need to complete this flow once for every user you want to have an access_token for. After this you can use the refresh_token to request a new access_token when it expires without user interaction.

Preparing for authentication

Before starting the authentication progress you should make sure you have the following:

• You should generate a cryptographically random string, named the code_verifier, unique for each new authentication request. The minimum length is 43 characters.
• Setup an redirect_uri we can send our users to in order to return to your application. e.g. you can use http://localhost:any-port and start a temporary HTTP server in your application to listen for requests. Or you can register your own schema e.g. appname:// that will open your application when a user navigates to e.g. appname://oauth?code=123SDG5234 in the browser.

Your redirect_uri should never change. You need to tell us what your redirect_uri is so we can register it to secure our system. Unregistered redirect_url's will get rejected when your application is live.

Step 1 - Sending users to the authorize page

Your web or mobile app should redirect users to the following URL in a native browser (do not use your own webview inside your app):

https://accounts.bakeronline.be/oauth/authorize

The following values should be passed as GET parameters (in the query string):

• client_id - issued when you created your app (request one if you don't have one)
• scope - a space separated list of the permissions you request (More info)
• response_type - should be equal to 'code'
• redirect_uri - URL to redirect back to when the authorization finished (either succeeded or failed)
• code_challenge - BASE64-encoded string of the SHA256 hash of the code_verifier
• code_challenge_method - should be equal to 'S256'
• state - unique string to be passed back upon completion (optional)

Full documentation

The state parameter should be used to avoid forgery attacks by passing in a value that's unique to the user you're authenticating and checking it when auth completes.

Step 2 - Users are redirected to your URI with a verification code

If the user authorizes your app, Bakeronline will redirect back to your specified redirect_uri with a temporary code in a code GET parameter, as well as a state parameter if you provided one in the previous step. If the states don't match, the request may have been created by a third party and you should abort the process.

e.g. we'll send the user to the following URL in the browser: appname://oauth?code=123SDG523sdg-sdgsd-qsdgaz4&state=abc12394559sd

You'll need to extract the code and state parameters.

Step 3 - Exchanging a verification code for an access token

With the code you received your application can send a POST request with the code and the code_verifier to request an access_token.

Full documentation (use grant_type = code)

In the end you'll receive the access_token and the refresh_token to start authenticating requests:

{
    "access_token": "ec4ad8b4eb6e32d41cc1b2a76d1f3c9b8b0e5bc52cccf95a32b25d8c485a963270e21c5f0bcc31e8919b66c4de84b7ef0541584734d1e32de5376103cff157b99cdb6345684d7e65217d22adaafc0f6dd8887720478efcfa8d57504742715011195a6b9a8022b17f603edf7b29a282bdba18026853419b08e1967b101e040b6d",
    "token_type": "Bearer",
    "expires_in": 3600,
    "refresh_token": "ec4ad8b4eb6e32d41cc1b2a76d1f3c9b8b0e5bc52cccf95a32b25d8c485a963270e21c5f0bcc31e8919b66c4de84b7ef0541584734d1e32de5376103cff157b9bfdfe1250389ada3acb5acf6713036c46aacef14fa624d1fb342e6c88bae58bf62c58a75346bad31bd3632e5ee69955e7c0bddaa782c5c50a53350b25e472501eb25ddb1db38022f122209b9b7d9e0d4e77d90f8b957cd94153332e4e50ba22fba435e0a099b43e7b7a76169af502cc450761fd07cdfdeda433b3ef531d54982ed103cb4c7903c1794dda58af603e2e5c47582568e5f4c191618f112fad6325f6fe7aaa90b3dd3c5b0168f5dc8a4fbb2d818b2e07db9fe2e1123fc335ed89cdb6345684d7e65217d22adaafc0f6dd8887720478efcfa8d57504742715011195a6b9a8022b17f603edf7b29a282bdba18026853419b08e1967b101e040b6d"
}

Step 4 - Refreshing your token

When your access_token expires (by default every hour) you need to request a new token with your refresh token. You'll start receiving the expired_access_token error code when this happens.

Full documentation (use grant_type = refresh_token)

You'll receive both a new refresh_token and an access_token