Discussions
How to Choose the Right Access Token Scopes
I’m still uncertain about how to choose the right access token scopes. From what I gathered in the documentation, it seems we can list multiple scopes by passing them as a space-delimited string to the ‘authorization code’ endpoint. Is there a comprehensive list of all available scopes?
Initially, I thought there were just a few options, like exports, core_data, and offline_access (as shown in the first screenshot). However, I’ve noticed other scopes, such as email and profile, are also available (as seen in the second screenshot).
https://developer.candis.io/reference/get-authentication-code
https://developer.candis.io/docs/token-exchange
Also, the scope is not required as a parameter. What privileges does a token have if no scope is passed? From what I’ve observed, it seems I can still use the Invoice and Export endpoints without specifying any scope.
I'd be thankful for some clarification. 🙏
The offline_access scope is particularly important if you need extended token validity. When included, it allows token exchanges to remain valid for an extended period (up to ~2 years) without requiring users to log in again. This is especially useful for long-running applications or background services.
You can obtain tokens without specifying any scopes. These tokens will have a shorter lifespan - if you need longer lifespan, you will need to include the offline_access scope.
Regarding exports and core_data - these are currently experimental scopes and we don't enforce strict validation on them at this time.
Some scopes like email and profile are considered core functionality and are enabled by default for all clients - you don't need to explicitly include these in your scope requests.
We will include this information in our documentation.
I hope this helps clarify the scope behavior! Let me know if you have any other questions about token management.
Thank you for the explanation!
I’m indeed looking to maximize the lifespan of the access token so that I can avoid requiring the data owner to reauthenticate frequently.
If I understood correctly, when I use the scope offline_access, the returned refresh token will be valid significantly longer than the access token itself and can therefore be used to obtain a new access token.
However, it appears that my current refresh token is valid for only about 180 days, based on the refresh_expires_in value in the Create or Refresh Access Token endpoint response (shown below).
Is there any way to extend this refresh token’s validity period? Or, how can I achieve the full two-year duration you mentioned?
The refresh_expires_in: 15551982 (about 6 months) indicates the lifespan of your current refresh token. Each time you perform a token exchange using this refresh token, you will get a new refresh token which is valid for another 6 months. You can continue this token exchange process for up to 2 years (after 2 years your offline access will expire).
I see. Thanks for the clarification! 🙏