We will try and help you on your way in a few simple steps. If you have any questions please ask us at [email protected]

1. Get the ID and Secret up and running How do I request OAuth Client ID and Secret?

2. The redirect URL provided will be the place the user is returned to in your website when the authentication was successful. Meaning you now have access to send API calls.

(Required) The client_id and redirect_uri are required parameters, if one or both are missing the request will result in an Invalid OAuth2 request and the default Billit login page respectively.

(Optional) The state can be a GUID or any other type of content, the value will also be present in the redirectURI after a successful login attempt as the state query param. This is typically used to prevent cross-site request forgery attacks.
Note: the usage of state is required when providing own query params as these are not allowed in the redirect_uri. Multiple parameters will have to be split with any character other than "&" as parameters following the "&" will not be returned in the state after logging in.

https://my.sandbox.billit.be/Account/Logon?client_id={CLIENTID}&redirect_uri={REDIRECTURI}&state={STATE}

The redirect has 2 states:

1. The access was given, the user is allowed temporary access and is redirected. The redirectURI will contain a query param -> "code={authorization_code}"

2. The access was denied, the user is redirected and the redirectURI will contain a query param -> "error=access_denied"

3. When the step before is successful you can now request the access token. This token has an expiry time frame, when this token expires you will have to refresh it.

Below you can see the endpoint used for generating the access token.

https://api.sandbox.billit.be/OAuth2/token

Required POST parameters

When providing the data to Billit we accept the following body type:

Application / json

4. When correctly posting to the Billit API you will have a JSON response coming back. This will look similar to what you see below.

{
  "token_type": "Bearer",
  "expires_in": 3600,
  "access_token": "{ACCESS_TOKEN}",
  "refresh_token":"{REFRESH_TOKEN}"
}

These tokens are also known as bearer tokens, allowing you to call the API in name of the person who granted permission via the OAuth connection.

GET https://api.sandbox.billit.be/v1/orders HTTP/1.1
Authorization: Bearer {ACCESS_TOKEN}
Accept: application/json

5. Tokens expire, so you might have to refresh them.
   After the time provided in the returned JSON ("Expires_In") the token will not be valid anymore. Luckily this does not mean the user has to re authenticate but the API can refresh the access.

You may use the same URL

https://api.sandbox.billit.be/OAuth2/token

But you will have to change the parameters

This will return a new token which you can use to execute API calls

Error states

{
  "errors": [
    {
      "Code": "InvalidAccessToken"
    }
  ]
}

{
  "errors": [
    {
      "Code": "AccessTokenExpired"
    }
  ]
}

{
  "errors": [
    {
      "Code": "AccessTokenRevoked"
    }
  ]
}