OAuth

What is OAuth and How is it used at Billit

OAuth is a way of letting a customer grant you access to their Billit account and allowing you to perform actions in their name. For this you need to have an OAuth client which needs to be requested, how can be found here How do I request OAuth Client ID and Secret?.

Every user you want to get access to as an integrator is required to login using the credentials of your client. After a successful login you can perform actions using the access token in the name of the corresponding user. As the tokens are linked to the client used in the authentication process in Billit. This means that trying to refresh an access token using another client will fail.

Since every user will login using the same client, it is advised to add a unique identifier in the URL used to send the users to the Billit login page to keep track of who is who. This can be achieved by either adding it in the redirect_uri (a wildcard will need to be set on the Billit side first) or by adding the identifier to the state parameter as these values will be returned after logging in.

The redirect URL provided when requesting an OAuth client is used to send the result to after a login attempt. Thus the place where users are returned to in your website when the authentication was successful or unsuccessful.

📘

One client to rule them all!

Only you as an integrator need a client, your users do not. They will make use of your client to grant you access.

Requesting access

Access to a user's profile and companies is requested via the OAuth login, here users can give their consent and grant you the necessary rigths as an integrator. To do this, redirect them to the Billit login with the example link below and fill in the required parameters.

• Send a request to [email protected] and make sure to provide all 4 parameters (If 1 is missing, we cannot proceed):
  • 1. Billit Party ID : for example "729999"
    • The Billit Party ID can be found when you login to your sandbox/production account and click on my company. Feel free to send the VAT number or My company URL to us if you are not certain.
  • 2. Redirect URI: https://your.app/oauth/callback
    • (we always need a redirect URL, must be delivered by you)
  • 3. Application Name : [YOUR APPLICATION NAME]
  • 4. Environment : Sandbox or Production

sequenceDiagram 
    participant App
    participant Billit
    
App->>Billit: send mail to [email protected] to to request Client ID and Secret for PartyID, AppName and Redirect URL on Sandbox.
Billit->>App: confirms with Client ID & Secret for Sandbox
App->>Billit: redirect user to Bililt Logon page with ClientID (required) & RedirectURL(required) & State (optional) 
Billit->>App: redirects user to redirectURL and AuthorizationCode
App->>Billit: calls Billit OAuth2/token with Client ID(required), Secret ID(required), AuthorizationCode(required) & Grant_type(required) & RedirectURL(required)
Billit->>App: returns the Bearer token needed by the app to call the Account,Order, Document or File API 

Feedback by Billit for sandbox : Confirmation that your Oauth setup is activated at Billit.

📘

Sample feedback:

• clientID: QPCDzzzKtPI99QzzEVzz
• clientSecret: U9GbSzz3sirizzQWEzzz.

What is State?

• This parameter is optional
• This is typically used to prevent cross-site request forgery attacks.
• 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.
• 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 request:

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

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

Next step is login by the user: (at least one time)

Result : see below.

The redirect result

The result after a user is redirected back to your site has 2 states, being:

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

   1. Example : https://eolauth.xpozzz.be:9999/billit/live/redirect?code=123456789

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

If the result is the first option, meaning access has been granted, then you can move on to the next step of requesting the access and refresh tokens. The access token has en expiry time frame allowing you access as long as it's active, when this token expires you will have to refresh it using the refresh token.

Token requisitioning

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

Required POST parameters in Json body

When sending the data to Billit make sure that: 1) body type is set to Application/json 2) Parameters are in Json body (see example below)

Example of a POST https://api.sandbox.billit.be/OAuth2/token content:

{
  "grant_type": "authorization_code",
  "code": "{AUTHORIZATION_CODE}",
  "client_id": "QPCDzzzKtPI99QzzEVzz",
  "client_secret": "U9GbSzz3sirizzQWEzzz",
  "redirect_uri": "https://staging.companyname.eu/apps/billit_callback"
}

Token requisitioning response

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, //seconds
  "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

Expires in : this is alway 3600. This is 3600 seconds, or 1 hour.

Refresh the access token

Access 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. If you keep on using it after expiration, you will get the error responsebody : "Code": "AccessTokenExpired". Luckily this does not mean the user has to re-authenticate, the API can refresh the access (Refresh can be done without login, also when the previous token has expired).

📘

Use the correct grant_type!

Make sure to use the grant_type "refresh_token" instead of "authorization_code" when trying to refresh an expired access token.

Required POST parameters

This will return a new token which you can use to execute API calls. The result will have the same content as the initial token request, except with different values.

Example

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

With Json body:

{
  "client_id": "QPCDzzzKtPI99QzzEVzz",
  "client_secret": "U9GbSzz3sirizzQWEzzz",
  "grant_type": "refresh_token",
  "refresh_token": "{The request token from the initial Json response}"
}

Error states

Below examples of error return information for 3 scenario's:

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

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

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

🚧

Never Share!

Please do not share your ID and Secret to any 3rd party. When Billit sends the data they will remove it from the thread.

Billit will never ask you to share the Secret or ID again