Authentication

To integrate an end-user’s data into your application, they must first authenticate with their digital asset provider(s) and grant permission for their data to be shared.

Authentication flow

Calico uses the OAuth 2.0 PKCE flow to keep user authentication secure and seamless. This industry-standard approach ensures that users can connect their financial accounts and share data with your app—without managing sensitive credentials.

Integration

Requirements

Your app must have:

Redirect URI: the page in your app where the user will return after authentication.

Client id and client secret: credentials issued by Calico.

Steps

Start of connection flow

Your app sends the end-user to Calico Connect to begin authentication. Use the widget URL and your client id.

https://widget.getcalico.com?client_id={YOUR_CLIENT_ID}

Authentication and authorization

Calico connects the user to their digital asset provider and obtains their consent to share read-only data with your app.

Return to your app

Calico returns the user to your app using your redirect URI + an authorization code. For example:

https://{YOUR_REDIRECT_URI}/?code={AUTHORIZATION_CODE}

Use the authorization code sent in the URL to get tokens for the user (next step).

Get tokens

Use the authorization code and your app credentials to make a token request. An access token will be returned.

curl -X POST https://login.getcalico.com/oauth/token\
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=authorization_code" \
-d "code={AUTHORIZATION_CODE}" \
-d "client_id={YOUR_CLIENT_ID}" \
-d "client_secret={YOUR_CLIENT_SECRET}" \
-d "redirect_uri={YOUR_REDIRECT_URI}"

Data Access

Use the access token as a bearer token for Calico API data calls.

curl --location --request GET 'https://api.getcalico.com/platform/v1/provider' \
--header 'Authorization: Bearer {token}'

Tokens

When a user authenticates, Calico issues a short-lived access token and a longer-lived refresh token. The access token is used to make authorized API requests on the user’s behalf. Once it expires, the refresh token can be used to obtain a new access token without requiring the user to log in again. This ensures secure, continuous access while minimizing the risk of token misuse.

Token Type	Purpose	Lifespan	Storage Best Practices
Access Token	Grants temporary access to protected resources	15 Minutes	Secure memory or encrypted storage. This should never be shared with more than one user.
Refresh Token	Used to obtain a new access token	1 Year	Secure, encrypted backend storage only.

Authentication flow#

Integration#

Requirements#

Steps#

Tokens#

Token lifecycle#

Authentication flow

Integration

Requirements

Steps

Tokens

Token lifecycle