Extension OAuth 2.0
All Fynd Commerce Extensions must use the OAuth 2.0 specification to authorize with the seller and access the Platform APIs. This guide will help you authorize your extension and obtain an access-token without using any libraries.
We recommend using one of our Extension helper libraries (JavaScript / Java / Python) to keep your Extension secure, avoid implementing OAuth, and focus on core logic. You can also use our CLI to generate starter code with these libraries.
If you're using an Extension helper library, you can skip this guide.
Overview
OAuth 2.0 is an industry-standard protocol for authorization that allows applications to access user resources without exposing their credentials. It provides a secure way to delegate access permissions through tokens, rather than sharing login details. OAuth 2.0 enables secure communication between the Extension and Fynd Commerce on behalf of sellers. Sellers can grant specific permissions to an Extension (like accessing order or product data) without sharing their credentials. This process involves obtaining an access-token, which the Extension uses to make authenticated API requests to Fynd Commerce, ensuring that the data access is secure, controlled, and revocable.
Authentication vs authorization
-
Authentication is the process of verifying the identity of the user or the Extension. To keep transactions on Fynd Commerce safe and secure, all Extensions must authenticate while making API requests.
-
Authorization is the process of granting permissions to Extensions. Sellers can authorize Extensions to access their data in Fynd Commerce. For example, an Extension might be authorized to access orders and product data in a Sales Channel.
API credentials
When an Extension is created on the Partner panel, an API key and API secret are generated. These credentials are used to authenticate your Extension during the authorization process.
Find these credentials: Partner panel → Extensions → your-extension → Client Credentials
OAuth flow
The following sequence diagram illustrates the authorization-code grant flow and access-token generation process:
- The seller opens the Extension or initiates a request to install it on Fynd Commerce.
- Fynd Commerce redirects the seller to the Extension's installation path.
- The Extension redirects the seller to Fynd Commerce OAuth page.
- Fynd Commerce displays the permissions page to the seller.
- The seller authorizes the Extension by consenting to the requested scopes.
- The Extension receives an authorization-code from Fynd Commerce.
- The Extension requests an access-token using the authorization-code.
- Fynd Commerce verifies the authorization-code and then issues and returns an access-token.
- The Extension requests the seller's data from Fynd Commerce using this access-token.
- Fynd Commerce validates the access-token and returns the requested seller data.
Step 1-2: Landing page
After a seller open your Extension or clicks the link to install it, Fynd Commerce ensures that the seller is logged in, and redirects the seller to /fp/install
path of your Extension URL with the following query parameters.
https://{extension_url}/fp/install
?company_id={company_id} # Id of the seller company installing or using the Extension.
&client_id={API_KEY}
&cluster_url={cluster_url} # api.fynd.com
Find
extension_url
: Partner panel → Extensions → your-extension → Edit Extension → Extension URL
Step 3-5: Permissions & Consent
If you do not have an access-token, if it has has expired, or if you need to change the access scopes, you can initiate the autorization process to obtain an authorizaton-code by redirecting the seller to the following URL with the specified query parameters:
https://api.fynd.com/service/panel/authentication/v1.0/company/{company_id}/oauth/authorize
&client_id={API_KEY}
&redirect_uri={redirect_uri}
&response_type=code
&scope={comma_seperated_scopes}
&state={random_string}
Query parameters
Parameter | Value |
---|---|
company_id | The Company ID where the extension is to be installed. |
client_id | The Extension API key. |
redirect_uri | The URL to redirect after the seller authorizes the Extension. Typically <extension-url>/fp/auth is used. |
response_type | code |
scope | A comma-separated list of access scopes (List of all scopes). |
state | A random string used for validation. |
If the access scopes have changed or if this the seller is installing the Extension for the first-time, Fynd Commerce will show the seller the permission page and get consent.
Step 6: Authorization-code grant
After the seller consents to the access scopes requested by the Extension, Fynd Commerce redirects them to the redirect_uri
provided in the previous step, with the following query parameters:
https://{redirect_uri} # Same URI from the previous authorization request.
?code={authorization_code} # Authorization-code.
&state={random_string} # Same random string as the previous request.
&client_id={API_KEY} # Extension API key.
&company_id={id} # Company ID where the Extension is being installed.
If the seller rejects the access scopes, the authentication flow will be interrupted, and you will not receive any API call on this redirect_uri
.
For security, ensure that the state
matches the one you previously provided to /oauth/authorize
page, and also validate the client_id
against your API key.
Step 7-8: Access-token
Once you have the authorization-code, you can now obtain an access-token. There are two types of access-token for interacting with the Fynd Commerce APIs: Offline and Online tokens.
Offline token | Online token | |
---|---|---|
Use Case | Ideal for background tasks like responding to webhooks or performing maintenance activities. | Best suited when you want to link the seller with all the activities in the API logs. |
Expiry | Valid for 1 hour. Can be refreshed indefinitely using the refresh token process. | Valid for 6 hours. Automatically renews the access-token in the background upon expiry. |
Tagging | A system user, created when an Extension is registered, is linked with all the API calls. | The authorizing seller is linked with all the API calls. |
Offline token
To obtain this offline access-token, send a POST
request to the following URL with the given headers and payload.
URL
POST https://api.fynd.com/service/panel/authentication/v1.0/company/{company_id}/oauth/offline-token
Payload
{ // Payload for "/oauth/offline-token"
grant_type: "authorization_code",
code: {authorization_code}, // Obtained in the previous step.
client_id: {API_KEY},
client_secret: {API_SECRET},
scope: {comma_seperated_scopes} // Scopes needed for offline access.
}
Headers
Header | Value |
---|---|
Authorization | Basic {API_KEY}:{API_SECRET} |
Content-Type | application/json |
Response
Upon a successful request, Fynd Commerce will respond with an access-token.
{ // Response for "/oauth/offline-token"
access_token: "<token>",
token_type: "<token_type>",
expires_in: "<ttl>",
expires_at: "<expires_at>",
refresh_token: "<refresh_token>",
scope: "<comma_seperated_scopes>"
}
The Authorization header requires base64 encoding of {API_KEY}:{API_SECRET}
. Example in bash:
"Authorization: Basic $(echo -n 'e85d3bd3e7ed8:Ul7D1nzof' | base64)"
Refreshing offline token
To refresh your offline access-token, make the same POST
request as above, but update the payload:
Payload
{ // Payload for access-token refresh
grant_type: "authorization_code",
code: {authorization_code}, // Obtained during authorization process (step 6).
refresh_token: {refresh_token} // Obtained along with the offline access-token.
}
URL, Headers & Response
Same as for obtaining the offline token.
Online token
To obtain an online access-token, you can send a POST
request to the /oauth/token
URL with the same headers and a lighter payload.
URL
POST https://api.fynd.com/service/panel/authentication/v1.0/company/{company_id}/oauth/token
Payload
{
grant_type: "authorization_code",
code: {authorization-code} // Obtained during authorization process (step 6).
}
Headers
Same as for obtaining the offline token.
Response
{ // Response for "/oauth/token"
access_token: "<token>",
token_type: "<token_type>",
expires_in: "<ttl>",
expires_at: "<expires_at>",
scope: "<comma_seperated_scopes>",
current_user: "<user_details>"
}
Step 9-10: API requests
Once you've obtained an API access-token, you can send authenticated requests to Fynd Commerce to get the seller's data. All the requests should have a valid access-token in header with the following format:
Header | Value |
---|---|
Authorization | Bearer {access_token} |
Learn more about Fynd Storefront GraphQL API and Fynd Platform API.
Example
To list all products available in the catalog using the Platform REST API in cURL, you can run:
curl -X GET "https://api.fynd.com/service/application/catalog/v1.0/products/"
-H "Authorization: Bearer xI8snq31S"
If an API call fails due to an expired access-token:
- For offline tokens, renew the access-token using a refresh token.
- For online tokens, restart the OAuth process to get a new access-token.