To integrate external applications with Cirqll, it is possible to create an OAuth client and authenticate Cirqll users with it. If you are unfamiliar with OAuth 2.0 and it's functions, read more on their official website: https://oauth.net/2/.Getting Started#
To integrate with Cirqll using OAuth 2.0, you'll need to create a client and authenticate users. Below are the key steps involved in the process:We recommend using an OAuth 2.0 package for the framework or programming language you are working in
Prerequisites#
You will need a redirect url (also known as a callback url). This is the URL where Cirqll will redirect users after they've authenticated and authorized your application to access their data.
1. Create a Client#
Pass these details to your OAuth2 client. Usually in a .env file or just hard-coded if you are just testing things out.In the example we use user.read.all customer.read.all customer.create.all customer.update.all contact.read.all contact.create.all contact.update.all as the scope. This enables us to index our colleagues, customers and contacts. As well as interact with customers and contacts (except for deleting them).
2. Authorize a User#
At the bottom of oauthdebugger.com a URL is generated with the values provided.You can leave out response_mode, state and nonce. But it is best to keep them to keep the authorization flow secure.https://api.cirqll.nl/oauth/authorize?client_id=$CLIENT_ID&redirect_uri=$REDIRECT_URI&scope=$SCOPE&response_type=code
3. Exchange code for tokens#
To exchange this code for access and refresh tokens, make a POST request to the Create Token endpoint.The URL will look like this:This request will return the following tokens:access_token: Used to authenticate API requests.
refresh_token: Used to obtain a new access token when the current one expires.
4. Refresh Access Token#
Access tokens are valid for 30 days. After this period, you will need to refresh the token to maintain access to the user's data. You can refresh the token by making a request to the Refresh endpoint.If the refresh_token has expired (after 3 months), the user will need to re-authorize the application.The URL to refresh the token will look like:
5. Fetch Authorized User Data#
Once you have successfully obtained an access token, you can retrieve the authenticated user's profile and their associated company data by making a request to the Me endpoint. 