All Fynd Platform Extensions must obtain authorization using the OAuth 2.0 specification to use Fynd’s Platform APIs.
This guide will help you authorize your extension from scratch without using any external library. It is recommended to use Fynd’s extension library to keep your extesnsion secure and reduce implementation time, as it already has OAuth implemented. If you're using the extension library, you don't need to follow this tutorial.
What you'll learn
After completing this tutorial, you'll be able to authorize your extension using an authorization code grant.
Requirements
- You've registered on Fynd Partners and created a partner organization
- You're familiar with the OAuth flow in Fynd Platform.
- Your extension is not created through FDK CLI or is not using Extension Library. Extension Library has OAuth pre-implemented
Step 1: Retrieve Extension Credentials
Obtain your API key and API secret key by creating an extension. These credentials are crucial for identifying your app during the authorization process. Follow these steps to retrieve the credentials for your extension:
- Log in to your Fynd Partners account.
- Here, if you have access to any organization you will get the screen to select a organization, otherwise it will open Create Organization form.
- Select the organization from the organization list, it will open the Fynd Partners Dashboard.
- Click on the Extension tab in the sidebar, then Create Extension.
- Choose the type of extension you want to create, fill in all mandatory details, and click Create Extension.
- In the Extension Overview, you can check your Extension’s API key and API secret in Client Credentials section.
Step 2: Initiate Authorization Flow
Before an extension can access any Fynd platform data, it needs to acquire an access token. The extension begins this process by redirecting the seller through the authorization code flow and retrieving an authorization code. The Fynd platform ensures that the seller grants the necessary permissions required by your extension before issuing an authorization code.
When a seller installs your extension, it triggers a GET request to the /fp/install route of the Extension URL (specified while creating the extension on the Partner Panel). This request includes company_id, client_id, and cluster_url as query parameters. In this route, the extension needs to initiate the authorization process.
To retrieve an authorization code, redirect the seller to the authorization consent page to the below URL. You can construct the redirect URL as mentioned below.
URL
https://api.fynd.com/service/panel/authentication/v1.0/company/{company_id}/oauth/authorize?access_mode={access_mode}&client_id={client_id}&redirect_uri={redirect_uri}&response_type=code&scope={scope}&state={random_string}Parameters
| Parameter name | Parameter Type | Description | isRequired |
|---|---|---|---|
| company_id | path | Company Id for which the extension is to be installed | yes |
| access_mode | query | Access mode, either offline or online. Default is offline | no |
| client_id | query | The API key for the extension (retrieved in Step 1) | yes |
| redirect_uri | query | The URL to which a seller is redirected after authorizing the extension, generally extension_url/fp/auth | yes |
| response_type | query | The type of response expected from the authorization server. Use response_type=code | yes |
| scope | query | A comma-separated list of scopes. Ex: to access data of company sales channel and company application settings, use scope=company/saleschannel,company/application/settings. To call an API in your extension, set the scope value based on the API you're using. You can find which scope each API requires in our API documentation. | yes |
| state | query | A random string. Ensure this matches the one you originally sent when you receive the authorization code | yes |
JS | Express
response.redirect("https://api.fynd.com/service/panel/authentication/v1.0/company/{company_id}/oauth/authorize?access_mode={access_mode}&client_id={client_id}&redirect_uri={redirect_uri}&response_type=code&scope={scope}&state={random_string}");When you send the seller to the authorization consent page, the seller will see a consent screen showing important information about the extension, including the permissions required by the extension from the seller.
If the seller accepts the consent, Fynd Platform will redirect the seller to the provided redirect_uri (generally extension_url/fp/auth). Here, your extension will receive code, state, client_id, and company_id as query parameters.
If the seller rejects the consent, the authentication flow will be interrupted, and you will not receive any API call on redirect_uri.
Step 3: Validate the Authorization Code
After the seller accepts the consent, Fynd redirects the seller to your extension’s server. Your extension will receive an authorization code on the redirect_uri route in the form of query parameters.
For example, if the redirect URL is extension_uri/fp/auth:
https://extension_uri/fp/auth?code={code}&state={state}&client_id={client_id}&company_id={company_id}| Parameter name | Description |
|---|---|
| code | Authorization code |
| state | The same string as the state query parameter you passed in the /oauth/authorize request. You need to validate it to match with your original state value |
| client_id | The API key for the extension (retrieved in Step 1) |
| company_id | Company ID for which the extension is to be installed |
Security Checks
Before proceeding, ensure your extension performs security checks to validate the OAuth callback. If any check fails, reject the request with an error and do not continue.
- Validate State: Ensure the
stateis the same one your extension provided to Fynd when asking for permission.
Step 4: Get an Access Token
Step 4.1: Get an Access Token for Online Access Mode
For more information on online access mode, please refer to the Fynd documentation.
After obtaining the authorization code on the /fp/auth route and verifying all security checks, you can request an access token from the following API:
Make a POST request to the /oauth/token endpoint with the parameters outlined below in the request body:
CURL
curl -X POST "https://api.fynd.com/service/panel/authentication/v1.0/company/{company_id}/oauth/token" \
-H "Authorization: Basic $(echo -n '{EXTENSION_API_KEY}:{EXTENSION_API_SECRET}' | base64)" \
-H 'Content-Type: application/json' \
-d '{"grant_type":"authorization_code","code":"{authorization_code}"}'Header:
| Header name | Description |
|---|---|
| authorization | Combination of api_key and api_secret. {api_key}:{api_secret} base64 string. Use Basic $(echo -n '{'{EXTENSION_API_KEY}'}:{'{EXTENSION_API_SECRET}'}' | base64) in the authorization header. |
Request Body
| Parameter | Description |
|---|---|
| code | The authorization code retrieved in Step 3 on the /fp/auth endpoint |
| grant_type | Grant type to access token. Use authorization_code |
Response
Upon a successful request, the server will respond with an access token:
{
"access_token": "<token>",
"token_type": "<token_type>",
"expires_in": "<ttl>",
"expires_at": "<expires_at>",
"scope": [...],
"current_user": "<user details>"
}Step 4.2: Get an Access Token for Offline Access Mode
For more information on offline access mode, please refer to the Fynd documentation.
If your extension needs to perform actions in offline mode, it needs an offline access token. Retrieve it by making a POST request to the /oauth/offline-token endpoint with the parameters outlined below:
CURL
curl -X POST "https://api.fynd.com/service/panel/authentication/v1.0/company/{company_id}/oauth/offline-token" \
-H "Authorization: Basic $(echo -n '{EXTENSION_API_KEY}:{EXTENSION_API_SECRET}' | base64)" \
-H 'Content-Type: application/json' \
-d '{"grant_type":"authorization_code","code":"{authorization_code}","client_id":"{api_key}","client_secret":"{api_secret}","scope":[...]}'Header:
| Header name | Description |
|---|---|
| authorization | Combination of api_key and api_secret {api_key}:{api_secret} base64 string. Use Basic $(echo -n '{'{EXTENSION_API_KEY}'}:{'{EXTENSION_API_SECRET}'}' | base64) in the authorization header. |
Request Body
| Parameter | Description |
|---|---|
| code | The authorization code retrieved in Step 3 on the /fp/auth endpoint |
| client_id | The API key for the extension. |
| client_secret | The API secret for the extension. |
| grant_type | Grant type to access token. Use authorization_code. |
| scope | A comma-separated list of scopes. Ex: to access data of company sales channel and company application settings, use scope=company/saleschannel,company/application/settings |
Response
Upon a successful request, the server will respond with an access token:
{
"access_token": "<token>",
"token_type": "<token_type>",
"expires_in": "<ttl>",
"expires_at": "<expires_at>",
"refresh_token": "<refresh_token>",
"scope": [...]
}Step 4.3: Renew an Access Token for Offline Access Mode Using the Refresh Token
The offline access token is crucial. If the access token expires, the extension can request a new token by providing the refresh token.
To renew the access token, make a POST request to the /oauth/offline-token endpoint with the parameters outlined below:
CURL
curl -X POST "https://api.fynd.com/service/panel/authentication/v1.0/company/{company_id}/oauth/offline-token" \
-H "Authorization: Basic $(echo -n '{EXTENSION_API_KEY}:{EXTENSION_API_SECRET}' | base64)" \
-H 'Content-Type: application/json' \
-d '{"grant_type":"authorization_code","code":"{authorization_code}","refresh_token":"{refresh_token}"}'Header:
| Header name | Description |
|---|---|
| authorization | Combination of api_key and api_secret {api_key}:{api_secret} base64 string. Use Basic $(echo -n '{'{EXTENSION_API_KEY}'}:{'{EXTENSION_API_SECRET}'}' | base64) in the authorization header. |
Request Body
| Parameter | Description |
|---|---|
| code | The authorization code retrieved in Step 3 on the /fp/auth endpoint |
| refresh_token | Refresh token retrieved in Step 4.2 |
Response
Upon a successful request, the server will respond with a renewed access token.
{
"access_token": "<token>",
"token_type": "<token_type>",
"expires_in": "<ttl>",
"expires_at": "<expires_at>",
"refresh_token": "<refresh_token>",
"scope": [...]
}Step 5: Redirect to Your Extension’s UI
After obtaining an access token, redirect the seller to your extension's UI, which should include the company_id parameter. Reference the formatted URL below:
https://extension_url/company/{company_id}After the successful installation of an extension within a company, whenever the seller visits the extension, it will trigger a complete restart of the authorization flow without prompting the user for consent again.
Step 6: Make Authenticated Requests to Platform APIs
After your extension has obtained an API access token, it can make authenticated requests to the Fynd Platform API.
These requests should include the following header:
Authorization: Bearer {access_token}For example, to retrieve a list of sales channels using the REST Platform API:
curl -X GET "https://api.fynd.com/service/platform/configuration/v1.0/company/{company_id}/application" \
-H "Authorization: Bearer {access_token}"If an authenticated request 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.
Step 7: Change the Granted Scopes (Optional)
After the seller has agreed to install your app, you might want to change the granted scopes. For example, you might request additional scopes if your integration requires access to additional data. To change scopes, redirect the user to the extension authorization link and request authorization of new permissions.