¶ OAuth2
BillRun supports OAuth2 standard since version 5.13.
¶ Generate id & secret
For creating an OAuth2 client id & secret, you can go to General Settings→Security tab and create client.
Once you received id & secret, you can now populate temporary token and use it for API authentication.
¶ Populate Token
URL: http://<HOST>/oauth2/token
Parameters can be under header user & password or request client_id & client_secret, accordingly to Name and Secret Key in the UI.
In addition, need to add the request grant_type variable with a value of client_credentials.
Examples as follow:
$ curl -X POST -u crm:3b3a53c8ab1f7de6256706ad0106d455 -d "grant_type=client_credentials" "http://billrun/oauth2/token"
or http request style:
$ curl -X POST -d "grant_type=client_credentials&client_id=crm&client_secret=3b3a53c8ab1f7de6256706ad0106d455" "http://billrun/oauth2/token"
Response should be in the following format:
{"access_token":"1abe535b260d170f24eb06f08e56cb7d639d3208","expires_in":3600,"token_type":"Bearer","scope":null}
Once you've received the token, you also received the expiration period under expires_in field.
¶ Using the token
For using the token, you can put in API request header or in the API request data. See example as follow:
$ curl --header 'Authorization: Bearer 1abe535b260d170f24eb06f08e56cb7d639d3208' "http://billrun/billapi/rates/uniqueget?query=%5B%5D"
or http request style:
$ curl "http://billrun/billapi/rates/uniqueget?query=%5B%5D&access_token=1abe535b260d170f24eb06f08e56cb7d639d3208"
The token will be expired in 1 hour, and the API response will be with failure and header 401 Unauthorized (instead of 200 OK). By this header response client can trigger re-generation of new token.
¶ More resources
Client examples: