Authorize Extension with OAuth

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:

1. Log in to your Fynd Partners account.
2. Here, if you have access to any organization you will get the screen to select a organization, otherwise it will open Create Organization form.
3. Select the organization from the organization list, it will open the Fynd Partners Dashboard.
4. Click on the Extension tab in the sidebar, then Create Extension.
5. Choose the type of extension you want to create, fill in all mandatory details, and click Create Extension.
6. 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 state is 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}

note

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.