Access Modes
This guide provides an overview of the different access modes to help you choose the appropriate one for your token based on your extension’s requirements. Each mode serves a distinct purpose, depending on the needs of the extension. There are two types of access modes: Online and Offline.
Online Access
If your app requires access for a short duration or operates only when the user is available, you should use online access. During the OAuth authorization phase, explicitly request this access. Online access is intended for situations where the user interacts with your extension through the web.
// The `access_mode` key is used to request online access.
let FDKExtension = setupFdk({
...
access_mode: "online",
...
});
Authorization
- An online access token has an expiry time of 6 hours.
- Once the token expires, the authorization process automatically runs in the background to generate a new access token.
- Users do not need to repeat the access process, as access was granted during the extension installation.
- The logged-in user interacting with the extension is associated with all API calls made on the platform, ensuring that the user's name is referenced in all executed API calls.
Example
- Consider an extension that performs operations on sales channel data. The home page of this extension initially displays a list of available sales channels. To retrieve the details of these sales channels, the extension makes an API call using an online access token. The fetched details are then presented to the user for viewing. In this case, the online access token is used by the extension to access the required data.
Offline Access
Offline is the default access mode. Tokens with offline access are designed for long-term access to a store, where no user interaction is required. This mode is ideal for background tasks triggered by webhooks or maintenance work performed in background jobs.
// The `access_mode` key is used to request offline access.
let fdkExtension = setupFdk({
...
access_mode: "offline",
...
});
Authorization
Upon successful authorization, clients receive two types of access tokens (Online and Offline) and one refresh token in the response.
- Online Access Token: This token is included in the response and is used for tasks requiring online access.
- Offline Access Token: This token is valid for 1 hour. Once it expires, the refresh token can be used to obtain a new offline access token.
- Refresh Token: The refresh token allows clients to renew the offline access token when it expires.
- Since the offline access token is used without user interaction, no logged-in user is associated with activities performed using this token. Instead, a system user is created when an extension is registered in the partner panel. As a result, all API calls made using the offline access token are associated with the system user of the extension.
Example
-
The Bulk Coupon Generator extension allows users to generate coupons in bulk based on specified criteria. After the user defines the coupon quantity and type, the extension processes the generation in the background, even if the user closes the extension. Since the task runs without user interaction, an offline token is used for API calls and registering the generated coupons.
-
Another example of a background task is the cron server of an extension. A cron server operates at scheduled intervals, such as daily at 10 PM, and can be used for tasks like data cleanup or scheduled updates. In these scenarios, the offline access token is used to manage the automated processes.