Skip to main content

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 nameParameter TypeDescriptionisRequired
company_idpathCompany Id for which the extension is to be installedyes
access_modequeryAccess mode, either offline or online. Default is offlineno
client_idqueryThe API key for the extension (retrieved in Step 1)yes
redirect_uriqueryThe URL to which a seller is redirected after authorizing the extension, generally extension_url/fp/authyes
response_typequeryThe type of response expected from the authorization server. Use response_type=codeyes
scopequeryA 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
statequeryA random string. Ensure this matches the one you originally sent when you receive the authorization codeyes

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 nameDescription
codeAuthorization code
stateThe 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_idThe API key for the extension (retrieved in Step 1)
company_idCompany 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 nameDescription
authorizationCombination 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

ParameterDescription
codeThe authorization code retrieved in Step 3 on the /fp/auth endpoint
grant_typeGrant 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 nameDescription
authorizationCombination 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

ParameterDescription
codeThe authorization code retrieved in Step 3 on the /fp/auth endpoint
client_idThe API key for the extension.
client_secretThe API secret for the extension.
grant_typeGrant type to access token. Use authorization_code.
scopeA 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 nameDescription
authorizationCombination 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

ParameterDescription
codeThe authorization code retrieved in Step 3 on the /fp/auth endpoint
refresh_tokenRefresh 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.


Was this section helpful?