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 an OAuth 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 an OAuth Client#
2.
Upon successful creation, you'll receive the following credentials:Client ID: A unique identifier for your application.
Client Secret: A private key used to authenticate your application.
2. Authorize User#
To start the authorization process and allow users to log in and grant access to your application, redirect them to the Authorize page.This endpoint is a web page (not a JSON endpoint) where users will authenticate and approve access.You must specify scopes for the data you wish to access. Cirqll does not provide default scopes. To view the available scopes, consult the Scopes endpoint. The redirect_uri you provide during the authorization request must match the one specified when creating the client.
[client_id] is the client ID you received earlier.
state is a random string used to prevent cross-site request forgery (CSRF).
[redirect_uri] is the same redirect URL you specified earlier.
For extra security, Cirqll supports the PKCE extension for OAuth 2.0. It is highly recommended to use PKCE in your integration.
3. Exchange Authorization Code for Tokens#
Once the user logs in and grants permission, they will be redirected back to your redirect_uri with an authorization code in the query parameters.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.To fetch both the user data and their associated company information, make a request to the /auth/me endpoint with the with=company query parameter. 